Structure

The JSON Web Token consists of three parts separated by a period "." (see the specification for detailed descriptions of each component):

1) JOSE Header - JSON structure containing metadata about the JWT such as signature algorithm

2) Claim Set - JSON structure containing standard and application specific claims

3) Signature - (Optional) Signature

Each part is Base64URL encoded to make the entire structure URL safe.

Validation

JWTs are signed with the private key of the Identity Server that generated the token. In order to validate the signature:

1) Verify that the issuer claim matches the expected domain of the issuing server.

2) Obtain the public key for the server in question by using the information contained in the OpenID Connect Discovery document.

3) Use the public key to check the validity of the signature. The algorithm used should be determined ahead of time. Do NOT trust the algorithm specified in the JOSE header, it is insecure. All OIT signatures will use the RS256 algorithm.

4) Check the expiration claim to make sure that the JWT is still valid. (Note: the expiration claim is a unix timestamp in seconds, not miliseconds)

Claims

Most claims are in the format of a URL for guaranteed uniqueness. The URL format does not imply that there is a resource located at that URL.

Standard Claims

The JWT specification includes a number of possible claims. The JWT contains the following standard claims:

Claim Value
iss

Issuing entity. This will be the domain of the identity server used to create the JWT. Adding the URI fragment "/.well-known/openid-configuration" to the value will produce the location of the OpenId Connect Discover document for this domain. See the OpenId Connect Discovery document for details on using this value. See validation instructions above for information about using this claim.

exp Expiration time in Unix format

WSO2 Claims

WSO2 populates the JWT with a number of application specific claims.

Claim Value
http://wso2.org/claims/subscriber The netid of the user that subscribed to this API.
http://wso2.org/claims/applicationid Internal WSO2 application identifier.
http://wso2.org/claims/applicationname The name of this application.
http://wso2.org/claims/applicationtier The throttling tier assigned to this application.
http://wso2.org/claims/apicontext

The context used in this API call (may or may not include version).

http://wso2.org/claims/version The version of this API.
http://wso2.org/claims/tier The throttling tier assigned to this user.
http://wso2.org/claims/keytype The type of keys used in this call. Possible values are "PRODUCTION" or "SANDBOX".
http://wso2.org/claims/usertype The type of OAuth 2.0 grant used for authorization. "APPLICATION_USER" for grant types that include a Resource Owner (authorization_code, implicit, resource owner password). "APPLICATION" for those that only have a Client (client credentials).
http://wso2.org/claims/enduser

The netid of the resource owner in the form of "netid@carbon.super"

http://wso2.org/claims/enduserTennantId

The WSO2 tenant id. (This value can be ignored since we don't have multiple tenants)

http://wso2.org/claims/client_id The OAuth 2.0 client id used for authorization. (This value is WSO2 claim but was added by BYU)

BYU Claims

BYU has added a number of claims to make processing of identity information easier for service providers. The content of the Resource Owner and Client claims will be dependent upon which OAuth 2.0 grant type was used for authorization and if there has been a relationship established between the client application and a BYU entity (non-person person). That relationship is defined by placing a entry in the IAM.Credentials table within CESPRD. The entry would have the following values:

CREDENTIAL_NAME - The WSO2 Client Id for the application to be linked to a BYU entity.

CREDENTIAL_TYPE - 'WSO2_CLIENT_ID'

BYU_ID - The BYU ID of the BYU entity to link this application to.

All other values in the table should be filled in with the appropriate information.

Relationship records should only be added for applications under the control of a BYU entity. There is no need to add them for individuals publishing their own applications. Currently there is no defined process for approving and adding these relationship records.

Some BYU claims are optional based upon the OAuth 2.0 grant type used. For example, if the Client Credentials grant type is used no Resource Owner exists and so the claims dealing with Resource Owner values will not be present in the JWT. The set of possible BYU specific claims are as follows:

Claim Value
http://byu.edu/claims/resourceowner_person_id
The person_id of the Resource Owner
http://byu.edu/claims/resourceowner_byu_id
The byu_id of the Resource Owner
http://byu.edu/claims/resourceowner_net_id
The net_id of the Resource Owner
http://byu.edu/claims/resourceowner_surname
The surname of the Resource Owner
http://byu.edu/claims/resourceowner_surname_position
The position of the surname of the Resource Owner when joining with the rest_of_name.
http://byu.edu/claims/resourceowner_rest_of_name
The rest_of_name of the Resource Owner. Typically the first and middle names.
http://byu.edu/claims/resourceowner_preferred_first_name
The preferred_first_name of the Resource Owner.
http://byu.edu/claims/resourceowner_sort_name
The full name of the Resource Owner combined for sorting purposes.
http://byu.edu/claims/resourceowner_suffix
The suffix (Jr, Sr, etc.) of the name of Resource Owner.
http://byu.edu/claims/resourceowner_prefix
The prefix (Dr, Mr, etc.) of the name of the Resource Owner.
http://byu.edu/claims/client_subscriber_net_id
The net_id of the person that subscribed to the called API. This is also the person that owns the client application in most cases. This is a cleaned up version of the http://wso2.org/claims/subscriber claim.
http://byu.edu/claims/client_claim_source

The source of the name and identifier information in the client claims defining the owner of the client application. Possible values are:

'CLIENT_SUBSCRIBER' - No relationship was found for this client application in the IAM.CREDENTIALS table. All values are based upon the value of the http://byu.edu/claims/client_subscriber_netid claim.

'CLIENT_ID' - A relationship was found for this client application in the IAM.CREDENTIALS table. All values are based upon the byu_id from that relationship.

http://byu.edu/claims/client_person_id
The person_id of the owner of the client application.
http://byu.edu/claims/client_byu_id
The byu_id of the owner of the client application.
http://byu.edu/claims/client_net_id
The net_id of the owner of the client application. Could be blank if no net_id has been defined for a BYU entity.
http://byu.edu/claims/client_surname
The surname of the owner of the client application.
http://byu.edu/claims/client_surname_position
The surname_position of the owner of the client application.
http://byu.edu/claims/client_rest_of_name
The rest_of_name of the owner of the client application.
http://byu.edu/claims/client_preferred_first_name
The preferred_first_name of the owner of the client application.
http://byu.edu/claims/client_sort_name
The full name of the owner of the client application combined for sorting purposes.
http://byu.edu/claims/client_name_suffix
The name suffix of the owner of the client application.
http://byu.edu/claims/client_name_prefix
The name prefix of the owner of the client application.

 

Examples

There are four possible combinations of the values of the http://wso2.org/claims/usertype and http://byu.edu/claims/client_claim_source claims.

1) OAuth 2.0 Grant type with a Resource Owner and no relationship between the client application and a BYU entity (http://wso2.org/claims/usertype = 'APPLICATION_USER' and http://byu.edu/claims/client_claim_source = 'CLIENT_SUBSCRIBER')

{
  "iss": "https://api.byu.edu",
  "exp": 1449198389105,
  "http://wso2.org/claims/subscriber": "BYU/bdm4",
  "http://wso2.org/claims/applicationid": "1",
  "http://wso2.org/claims/applicationname": "DefaultApplication",
  "http://wso2.org/claims/applicationtier": "Unlimited",
  "http://wso2.org/claims/apicontext": "/testapi/RestEchoService/v1",
  "http://wso2.org/claims/version": "v1",
  "http://wso2.org/claims/tier": "Unlimited",
  "http://wso2.org/claims/keytype": "PRODUCTION",
  "http://wso2.org/claims/usertype": "APPLICATION_USER",
  "http://wso2.org/claims/enduser": "bdm4@carbon.super",
  "http://wso2.org/claims/enduserTenantId": "-1234",
  "http://wso2.org/claims/client_id": "2hZhnFK3i8dtYaV3xE_RaXE_o0Ma",
  "http://byu.edu/claims/resourceowner_person_id": "999999999",
  "http://byu.edu/claims/resourceowner_byu_id": "888888888",
  "http://byu.edu/claims/resourceowner_net_id": "bdm4",
  "http://byu.edu/claims/resourceowner_surname": "Moore",
  "http://byu.edu/claims/resourceowner_surname_position": "L",
  "http://byu.edu/claims/resourceowner_rest_of_name": "Brent D",
  "http://byu.edu/claims/resourceowner_preferred_first_name": "Brent",
  "http://byu.edu/claims/resourceowner_sort_name": "Moore, Brent D"
  "http://byu.edu/claims/resourceowner_suffix": " ",
  "http://byu.edu/claims/resourceowner_prefix": " ",
  "http://byu.edu/claims/client_subscriber_net_id": "bdm4",
  "http://byu.edu/claims/client_claim_source": "CLIENT_SUBSCRIBER",
  "http://byu.edu/claims/client_person_id": "999999999",
  "http://byu.edu/claims/client_byu_id": "888888888",
  "http://byu.edu/claims/client_net_id": "bdm4",
  "http://byu.edu/claims/client_surname": "Moore",
  "http://byu.edu/claims/client_rest_of_name": "Brent D",
  "http://byu.edu/claims/client_surname_position": "L",
  "http://byu.edu/claims/client_preferred_first_name": "Brent",
  "http://byu.edu/claims/client_sort_name": "Moore, Brent D",
  "http://byu.edu/claims/client_name_suffix": " ",
  "http://byu.edu/claims/client_name_prefix": " ",
}

 

2) OAuth 2.0 Grant type with a Resource Owner and and existing relationship between the client application and a BYU entity (http://wso2.org/claims/usertype = 'APPLICATION_USER' and http://byu.edu/claims/client_claim_source = 'CLIENT_ID')

{
  "iss": "https://api.byu.edu",
  "exp": 1449196008421,
  "http://wso2.org/claims/subscriber": "BYU/bdm4",
  "http://wso2.org/claims/applicationid": "1",
  "http://wso2.org/claims/applicationname": "DefaultApplication",
  "http://wso2.org/claims/applicationtier": "Unlimited",
  "http://wso2.org/claims/apicontext": "/testapi/RestEchoService/v1",
  "http://wso2.org/claims/version": "v1",
  "http://wso2.org/claims/tier": "Unlimited",
  "http://wso2.org/claims/keytype": "PRODUCTION",
  "http://wso2.org/claims/usertype": "APPLICATION_USER",
  "http://wso2.org/claims/enduser": "bdm4@carbon.super",
  "http://wso2.org/claims/enduserTenantId": "-1234",
  "http://wso2.org/claims/client_id": "2hZhnFK3i8dtYaV3xE_RaXE_o0Ma",
  "http://byu.edu/claims/resourceowner_person_id": "999999999",
  "http://byu.edu/claims/resourceowner_byu_id": "888888888",
  "http://byu.edu/claims/resourceowner_net_id": "bdm4",
  "http://byu.edu/claims/resourceowner_surname": "Moore",
  "http://byu.edu/claims/resourceowner_surname_position": "L",
  "http://byu.edu/claims/resourceowner_rest_of_name": "Brent D",
  "http://byu.edu/claims/resourceowner_preferred_first_name": "Brent",
  "http://byu.edu/claims/resourceowner_sort_name": "Moore, Brent D"
  "http://byu.edu/claims/resourceowner_prefix": " ",
  "http://byu.edu/claims/resourceowner_suffix": " ",
  "http://byu.edu/claims/client_subscriber_net_id": "bdm4",
  "http://byu.edu/claims/client_claim_source": "CLIENT_ID",
  "http://byu.edu/claims/client_person_id": "777777777",
  "http://byu.edu/claims/client_byu_id": "66666666",
  "http://byu.edu/claims/client_net_id": " ",
  "http://byu.edu/claims/client_surname": "Core Services",
  "http://byu.edu/claims/client_surname_position": "L",
  "http://byu.edu/claims/client_rest_of_name": " ",
  "http://byu.edu/claims/client_preferred_first_name": " ",
  "http://byu.edu/claims/client_sort_name": "Core Services",
  "http://byu.edu/claims/client_name_prefix": " ",
  "http://byu.edu/claims/client_name_suffix": " ",
}

 

3) OAuth 2.0 Grant type with no Resource Owner and no relationship between the client application and a BYU entity (http://wso2.org/claims/usertype = 'APPLICATION' and http://byu.edu/claims/client_claim_source = 'CLIENT_SUBSCRIBER')

{
  "iss": "https://api.byu.edu",
  "exp": 1449198083615,
  "http://wso2.org/claims/subscriber": "BYU/bdm4",
  "http://wso2.org/claims/applicationid": "1",
  "http://wso2.org/claims/applicationname": "DefaultApplication",
  "http://wso2.org/claims/applicationtier": "Unlimited",
  "http://wso2.org/claims/apicontext": "/testapi/RestEchoService/v1",
  "http://wso2.org/claims/version": "v1",
  "http://wso2.org/claims/tier": "Unlimited",
  "http://wso2.org/claims/keytype": "PRODUCTION",
  "http://wso2.org/claims/usertype": "APPLICATION",
  "http://wso2.org/claims/enduser": "bdm4@carbon.super",
  "http://wso2.org/claims/enduserTenantId": "-1234",
  "http://wso2.org/claims/client_id": "2hZhnFK3i8dtYaV3xE_RaXE_o0Ma",
  "http://byu.edu/claims/client_subscriber_net_id": "bdm4",
  "http://byu.edu/claims/client_claim_source": "CLIENT_SUBSCRIBER",
  "http://byu.edu/claims/client_person_id": "999999999",
  "http://byu.edu/claims/client_byu_id": "888888888",
  "http://byu.edu/claims/client_net_id": "bdm4",
  "http://byu.edu/claims/client_surname": "Moore",
  "http://byu.edu/claims/client_surname_position": "L",
  "http://byu.edu/claims/client_rest_of_name": "Brent D",
  "http://byu.edu/claims/client_sort_name": "Moore, Brent D",
  "http://byu.edu/claims/client_preferred_first_name": "Brent"
  "http://byu.edu/claims/client_name_suffix": " ",
  "http://byu.edu/claims/client_name_prefix": " ",
}

 

4) OAuth 2.0 Grant type with no Resource Owner and an existing relationship between the client application and a BYU entity (http://wso2.org/claims/usertype = 'APPLICATION' and http://byu.edu/claims/client_claim_source = 'CLIENT_ID')

{
  "iss": "https://api.byu.edu",
  "exp": 1449196866334,
  "http://wso2.org/claims/subscriber": "BYU/bdm4",
  "http://wso2.org/claims/applicationid": "1",
  "http://wso2.org/claims/applicationname": "DefaultApplication",
  "http://wso2.org/claims/applicationtier": "Unlimited",
  "http://wso2.org/claims/apicontext": "/testapi/RestEchoService/v1",
  "http://wso2.org/claims/version": "v1",
  "http://wso2.org/claims/tier": "Unlimited",
  "http://wso2.org/claims/keytype": "PRODUCTION",
  "http://wso2.org/claims/usertype": "APPLICATION",
  "http://wso2.org/claims/enduser": "bdm4@carbon.super",
  "http://wso2.org/claims/enduserTenantId": "-1234",
  "http://wso2.org/claims/client_id": "2hZhnFK3i8dtYaV3xE_RaXE_o0Ma",
  "http://byu.edu/claims/client_subscriber_net_id": "bdm4",
  "http://byu.edu/claims/client_claim_source": "CLIENT_ID",
  "http://byu.edu/claims/client_person_id": "77777777",
  "http://byu.edu/claims/client_byu_id": "66666666",
  "http://byu.edu/claims/client_net_id": " ",
  "http://byu.edu/claims/client_sort_name": "Core Services",
  "http://byu.edu/claims/client_surname": "Core Services",
  "http://byu.edu/claims/client_surname_position": "L",
  "http://byu.edu/claims/client_preferred_first_name": " "
  "http://byu.edu/claims/client_rest_of_name": " ",
  "http://byu.edu/claims/client_name_prefix": " ",
  "http://byu.edu/claims/client_name_suffix": " ",
}