Local

The Local Authentication Provider enables the Cloud CMS Application Server to connect to a locally implemented identity provider. The identity provider can be implemented within your own Node.js application or as part of a separate application using a completely different technology.

For more information on Authentication within the App Server, see App Server Authentication / SSO.

Configuration

Here are all of the properties that may be configured (default values are shown):

"auth": {
    "providers": {
        "myProvider": {
            "type": "local",
            "config": {
                "loginUrl": "/login",
                "authcodeName": "authcode",
                "authcodeSecret": "authcodeSecret",
                "authcodeIssuer": "authcodeIssuer",
                "properties": {
                    "id": "unique_name"
                }
            }
        }
    }
}

Where the configuration properties are:

• loginUrl - (optional) property to identify where the login screen is located. This could be a relative or absolute URL to an external service.
• authcodeName - (optional) the name of the authentication code request parameter
• authcodeSecret - (optional) the secret key to use to symmetrically encrypt the auth code. This must match what you use in your adapter.
• authcodeIssuer - (optional) the issuer of the auth code. This must match what you use in your adapter.
• properties.id - (optional) the field in the authcode profile that identifies the user

How it Works

When someone needs to log in on your web site, either intentionally or as part of a redirected filter flow, they will be taken to the /auth/myProvider route. This route will call the handleAuth() method on the local provider. This method will redirect to the loginUrl as configured above.

The loginURL will need to be implemented by you. It should contain a form where the user can log in. Once submitted, the form handler (implemented by you) should authenticate the user. If the user is successfully authenticated, then a call should be made back to the Application Server to indicate that things succeeded.

This success call should be a GET to /auth/myProvider/callback. It should include a single request parameter whose name is specified by config.authcodeName above. Like this:

GET /auth/myProvider/callback?authcode={authcodeValue}

Where authcodeValue is a JWT signed token consisting of a payload that looks like this:

{
    "profile": {
        ... authenticated profile
    }
}

The JWT signature requires a secret and an issuer. The Local Provider receives this token and then unpacks it using the same shared secret and issuer. It is important that only the Application Server and the Identity Provider share these values so as to prevent spoofing.

For further security considerations regarding the exchange of this authcode, we suggest the use of HTTPS and IP whitelisting, if required.

Once the Local Provider has extracted the payload, it will have the authenticated profile and things will proceed as expected.