Introduction

Like all SOAJS microservices, OAuth microservice has different layers of configuration. Local configuration, tenant-level configuration if the microservice is a multitenant one, and registry configuration. Moreover, OAuth can have a custom separate database for tokens and users. 

Configuration Layers

1 - Tenant configuration

Provisioning is a configuration that all SOAJS micro-services can acquire once you turn on multi-tenant for them. Once a service becomes multi-tenant, you can provide custom tenant configuration to it at run time. If you have 2 tenants that can access the oAuth service, then the provisioned configuration for each tenant will be loaded once that tenant invokes an API in oAuth.

The below configuration is supported by the oAuth micro-service and can be configured & changed at the tenant level under the Manage Pillar.

{
    _id: "%tenant_id%",
    ...
    oauth: {
        secret: "tenant_oauth_secret",
        pin: {
            "%product_name%": {
                enabled: true
            }
        },
        disabled: 0, //OAuth enabled or not
        type: 2,//OAuth type
        loginMode: "%login_mode%"
    },
    ....
}

Follow the Configuration Steps to add and update tenant configuration for OAuth

You can change the values of the below variables to customize secret, type, and loginMode

2 - Environment configuration (registry)

This configuration is on the environment level. OAuth configuration can be added from SOAJS Console.

{
	_id: "%environment_id%",
	services: {
		...
		config: {
			...
			oauth: {
				grants: [
					"password",
					"refresh_token"
				],
				debug: false,
				getUserFromToken: true,
				accessTokenLifetime: 7200),
				refreshTokenLifetime: 1209600
			},
			...
		}
	}
}

Follow the Configuration Steps to add and update environment configuration for OAuth

You can change the values of the below variables to customize grants, debug, getUserFromToken, accessTokenLifetime, and refreshTokenLifetime

3 - Custom registry configuration

SOAJS oAuth supports pin login.

So what is is pin login? think of it as a fast way to login by entering a code without the need to enter the complete login information each time aka (email and password).

When is this useful? this is useful in many cases, for example in the hospitality business you might want to turn on pin login so employee can easily key in a code and quickly access the system.

Can i control the code length and type? yes check out SOAJS URAC pin configuration 

Wrap the pin login API

If you decide not to consume the SOAJS oAuth pin API directly and add a wrapper around it, you will need to configure the wrapper at the custom registry level:

create under custom registry an entry with the following label: oauth

{
...
	pinWrapper: {
		"servicename": "myauthentieator",
		"apiname": "/pin"
	}
...
}

Pin Login Whitelist APIs

pin login is protected by accessToken which means a user with the right to trigger pin login must login first (we call this first login). Once logged in, the accessToken from the first login is used to trigger a pin login. The accessToken from the first login can only be used to request pin login. Once pin login is request and pin code is valid, an accessToken is provided and that accessToken must be used to access the APIs.

SOAJS provides the ability to whitelist APIs that can be requested by using the first login accessToken.

create under custom registry an entry with the following label: oauth

{
...
	pinWhitelist: {
		"servicename": {
			"method": {
				"apis": ["api1, api2", ...],
				"regex": ["for api with path param use regex", "/device/:id", ...]
			},
			...
		},
		"shoppingcart": {
			"get": {
				"apis": ["/cart", "/items"]
			}, 
			"post": {
				"apis": ["cart/item"]
			}
			...
		}
		...
	}
...
}

Roaming 

SOAJS oAuth provide the ability to roam between any environment and a soajs environment. This is very helpful if you want to create an environment and you want to offset all kind of authentication and authorization to SOAJS oAuth.

All what you have to do is the following:

1- add under custom registry an entry with the following label: oauth

{
...
	"roaming": {
		"services": {
			"servicename": {
				"whitelistips": ["127.0.0.1"]
			}
		}
	}
...
}

2- call the service but add to the header of your request "soajsroaming" to be true

Valid Response

{"result":true,"data":true}

Invalid Response

{"result":false,"errors":{"codes":[165],"details":[{"code":165,"message":"Roaming: Unable to login roamed user!"}]}}

4 - Separate Database for tokens and users

OAuth can have a separate database that can be added from Deploy tab in SOAJS Console → Databases

Follow the Configuration Steps below to create a database for OAuth

The database should have the name "oauth" to be used.

5 - Tenant Key Configuration (provision)

oauth: {
	loginMode: "urac", //oauth login mode,
	roaming: {
		whitelistips: [
			"192.168.0.1",
			"127.0.0.1"
		]
	},
	passportLogin: { // 3rd party integrations using passport
	    "github": {...},
		"facebook": {...},
		"twitter": {...},
		"google": {...},
	},
	azure: {...},
	openam: {...},
	ldapServer: {...}
}               

Follow the Configuration Steps to add and update the key configuration for OAuth

You can change the values of the below variables to customize loginMode and passportLogin

Useful Links

Passport Strategies: Define application keys for passport integration. Currently supporting Github, Twitter, Facebook, and Google. Go to the link for more information and an example of the configuration.

/wiki/spaces/OAUT/pages/1433927681: Azure Active Directory Authentication Libraries allow the integration with Azure AD.

OpenAM login: SSO (Single Sign-On).

LDAP (Lightweight Directory Access Protocol) login: Active directory login.