The WSO2 identity infrastructure is based upon OAuth 2.0 and OpenID Connect. These two standards define the interaction and data transmission between the client application and the WSO2 API Manager (APIM). This document is intended to describe the identity interaction between the client and the APIM. All interaction is based upon the WSO2 implementation of the OpenID Connect Specification.

There are three entities involved in the client application-APIM interaction:

Resource Owner - the end user of the client application (i.e. the person sitting at the keyboard)

Client Application - the application the Resource Owner is using to access protected resources

API Manager - The API Manager (via the Identity Server) which 1) issues and validates access tokens and 2) issues ID Tokens

ID Token Structure

The ID Token is defined as a JSON Web Token with a defined payload. The standard claims contained in the payload, along with their definitions, can be found in the OpenID specification. BYU has added a number of custom claims to the ID Token, in order to make the processing of university-specific data related to the Resource Owner more convenient for the client application.

BYU has added the following claims about the identity of the resource owner: person_id, byu_id, net_id, surname, surname_position, rest_of_name, sort_name, preferred_first_name, suffix; prefix. See the appropriate documentation about the contents and use of these fields (citation needed).

 

If the OAuth grant type does not involve a Resource Owner, the BYU claims will not be present in the ID Token.

The payload portion of the IDToken will look something like this:

{
  "sub": "BYU/bdm4@carbon.super",
  "azp": "2hZhnFK3i8dtYaV3xE_RaXE_o0Ma",
  "at_hash": "Y2QyNTc1NGU2OTEzMjdkOWNkYjQ1OTc1MjA4OWNkNWE=",
  "iss": "https://localhost:9443/oauth2endpoints/token",
  "iat": 1449197488308,
  "auth_time": 1449195076404,
  "exp": 1449201088308,
  "aud": [
    "2hZhnFK3i8dtYaV3xE_RaXE_o0Ma"
  ],
  "person_id": "500204392",
  "byu_id": "045325744",
  "net_id": "bdm4",
  "surname": "Moore",
  "surname_position": "L",
  "rest_of_name": "Brent D",
  "sort_name": "Moore, Brent D",
  "preferred_first_name": "Brent",
  "suffix": " ",
  "prefix": " "
}
Obtaining an ID Token

The basic identity interaction between the client application and the APIM consists of the following steps:

1) The client requests an OAuth access token using any of the supported grant types. Along with the standard OAuth request parameters, the client includes the scope 'openid' to indicate that it wants access to OpenID Connect identity information.

2) If the client is not using the implicit grant type, the authentication server will return an ID Token, along with the access token. Currently, WSO2 Identity Server does not support returning an ID Token during the implicit grant processing. If the client is using the implicit grant type the client can call the OpenID Connect user info endpoint to retrieve resource owner information.

3) The client validates the ID Token returned and accesses the identity information it contains. (Note: The steps to fully validate the token can be found in the OpenID Connect Specification; BYU-Specific JWT validation steps can be found here.