Single Sign-On

Neos integrates an Single Sign-On process. This mechanism allows implicit authentication from a third-party application.

On the third-party application, the user will perform an action to be redirected to a cluster by being authenticated without having to go through the authentication page.

How to set up SSO authentication ?

Development

In development, the configuration must be set up in the cluster configuration file. You must specify the different SSO connections and for each of them :

The type which is a unique name that represents the SSO connection.
The callback URL that the Framework will call to verify the token and obtain the user's information.

Authentication:
  # ...
  SingleSignOn:
    Foo:
      CallbackUrl: https://foo-app.com/sso-callback

It is possible to specify multiple SSO connections.

Authentication:
  # ...
  SingleSignOn:
    Foo:
      CallbackUrl: https://foo-app.com/sso-callback
    Bar:
      CallbackUrl: https://bar-app.com/sso-callback

On the third-party application, the action that will redirect the user to the cluster will have to redirect to the cluster /sso route by providing :

The type (type) corresponding to the type of the SSO connection defined in the cluster configuration file.
The token (token) that will be passed back to the callback URL to be verified and get the user's information.
The redirection URL (redirectUrl) which is optional and allows to redirect the user to a specific page of the cluster after the authentication.

For example : https://localhost/neos/northwind/sso?type=Foo&token=q6Xe45UfLPosHjXOfwG2HtJTkjxSn!veq0-cznSerlUw0DxiLPrs4EMM&redirectUrl=/?ui=InvoiceListUI

When the user arrives at this route, the callback URL will be called to verify the token and get the user's information. Example : https://foo-app.com/sso-callback?token=q6Xe45UfLPosHjXOfwG2HtJTkjxSn!veq0-cznSerlUw0DxiLPrs4EMM

The third-party application will have to verify the token. If the token is valid, it must return a JSON response with the status 200. The JSON must be in the following format:

{
  "identifier": "jdoe",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "context": {
    "CompanyCode": "C1"
  }
}

Only the identifer key is required. It is this key that identifies the user.

It is possible to pass a context which is a key/value dictionary. This dictionary is used to feed the application context.

Note

The values in the dictionary must be strings, as they are passed to the client through the URL. Since the type information is lost in this process, all values will be interpreted as strings.

After receiving the response, the Framework will implicitly authenticate the user and then redirect to the specified redirection URL.

Production

In production, Single Sign-On is configured at the Gateway level.

It must be put in the appsettings.json file of the Gateway in JSON format :

{
  "Authentication": {
    "Authority": "https://localhost:5001",
    "ClientId": "b68c22cc-6e48-4ff8-bf3f-49f70e388376",
    "Scopes": ["custom_scope"],
    "UserPropertiesMap": {
      "Name": "username",
      "Email": "principal_email"
    },
    "SingleSignOn": {
      "Foo": {
        "CallbackUrl": "https://foo-app.com/sso-callback"
      },
      "Bar": {
        "CallbackUrl": "https://bar-app.com/sso-callback"
      }
    }
  },
  "SingleSignOnRoutes": ["/sso"]
}

It is necessary to configure the routes used for the Single Sign-On connection via the SingleSignOnRoutes key.

Callback URL