Overview

When users are first moved to the Identity Service, any existing authentication information held in the existing application will be exchanged for an id from Identity Service. This id should be stored along side the user's record in the existing application.

During sign on, the user should be directed to the Identity Service Authorize Endpoint. Identity Service will handle the process of authenticating the end-user. Once the end-user is authenticated, the Identity Service will return an authentication response to the existing application. Details on this process can be found in the Authentication Api documentation.

The existing application will use the information in that authentication response to extract the end-user's subject claim (sub). This can either be accomplished with a call to the /api/userinfo endpoint or by reading the user's id_token.

The sub will match the id of the user who just authenticated. The existing application can then sign in the associated user.

Additional claims will be returned based on the scopes requested. These claims should be used to update the user information stored in the existing application. See the scopes documentation for a list of all supported claims.

Scopes

The OAuth2 protocol is a delegated authorization mechanism, where an application requests access to resources controlled by the user (the resource owner) and hosted by an API (the resource server), and the authorization server issues the application a more restricted set of credentials than those of the user.

The scope parameter allows the application to express the desired scope of the access request. In turn, the scope parameter can be used by the authorization server in the response to indicate which scopes were actually granted (if they are different than the ones requested).

OpenID Connect Scopes

OpenID Connect (OIDC) is an authentication protocol that sits on top of OAuth2, and allows the application to verify the identity of the users and obtain basic profile information about them in an interoperable way. This information can be returned in the ID Token and/or in the response from the /api/userinfo endpoint (depending on the type of request).

The basic (and required) scope for OpenID Connect is the openid scope. This scope represents the intent of the application to use the OIDC protocol to verify the identity of the user.

In OpenID Connect (OIDC), we have the notion of claims. There are two types of claims:

• Standard (which means they are defined in the OIDC specification)
• Custom

Standard Claims

OpenID Connect specifies a set of standard claims. These claims are user attributes and are intended to provide the application with user details such as email, name and picture.

The basic claim returned for the openid scope is the sub claim, which uniquely identifies the user (iss, aud, exp, iat, nbf and at_hash claims will also be present in the ID Token). Applications can ask for additional scopes to request more information about the user. The following additional scopes apply:

• profile: will request the claims representing basic profile information. These are name, family_name, given_name, middle_name, nickname, picture and updated_at. Note: Not all of these claims will actually be provided by the Identity Service. Currently, we only support name, family_name and given_name.
• email: will request the email and email_verified claims.
• phone: will request the phone_number and phone_number_verified claims.
• address: will request the address claim

Example: Ask for Standard Claims

In this example, we will use the OAuth 2.0 Implicit Grant to authenticate a user and retrieve an ID Token that contains the user's name, profile, and email information.

To initiate the authentication flow, send the user to the authorization URL and request an ID Token:

https://id.vancoplatform.com/oidc/authorize?
  scope=openid%20profile%20email&
  response_type=id_token&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://YOUR_APP/callback&
  nonce=YOUR_CRYPTOGRAPHIC_NONCE&
  state=YOUR_OPAQUE_VALUE

Notice that we included three values at the scope param: openid, profile (to get the name, family_name and given_name), and email (to get the email claim).

After Identity Service has redirected back to the app, you can extract the ID Token from the hash fragment of the URL. This can be done via the parseHash() method in login.js. When decoded, the ID Token contains the following claims:

{
  "sub": "86d4007b-3935-44af-9e47-6904b8316373",
  "name": "Jane Doe",
  "family_name": "Doe",
  "given_name": "Jane",
  "email": "[email protected]",
  "email_verified": true,
  "token_usage": "id_token",
  "aud": "YOUR_CLIENT_ID",
  "nonce": "YOUR_CRYPTOGRAPHIC_NONCE",
  "at_hash": "qv0NAB2P4yYffkJwQ35DnA",
  "nbf": 1531337491,
  "exp": 1531338691,
  "iat": 1531337491,
  "iss": "https://id.vancoplatform.com/"
}

Custom Claims

In addition to the standard OpenID Connect claims, Identity Service may also provide additional custom claims. Those claims are detailed below.

managed

If the user represented by the id_token is managed by a third-party upstream sso provider, Identity Service will set the managed claim automatically. The value will be an identifier of the third-party system that controls this user.

Managed users are not stored in Identity Service. Because of that, none of the partner apis will work for manged users. All authentication apis, including the /api/userinfo api, will work normally for managed users.

Currently, this will only happen for internal Vanco users controlled by Azure Active Directory. For these users, the managed claim will be set to InternalAzureAD

role

Use the roles scope to request access to a user's role. Users managed by Identity Service will not typically have roles, but users managed by other sso providers may have role information carried through from their sso provider.

In the case of Azure Active Directory, these roles can be derived from existing security groups. Using this feature with Internal Azure AD users can be a very quick way to set up role-based access control for internal users.