A JSON Web Token (JWT) is a standard way of communicating data between two parties. BYU uses the JWT specification for communicating identity information between our API Managers and back end services.
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 UCSD 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:
Display Name | Description | Claim Uri | Mapped Attribute (s) | UCSD Mapping |
|---|---|---|---|---|
| Employee ID | Employee ID | http://wso2.org/claims/eid | eid | urn:mace:ucsd.edu:sso:pps:eid |
| Student ID | Student ID (PID) | http://wso2.org/claims/pid | pid | urn:mace:ucsd.edu:sso:isis:pid |
| RACFID | racf/mainframe id | http://wso2.org/claims/racfid | racfid | urn:mace:ucsd.edu:sso:auth:racfid |
| AD Username | The user's Active Directory user name | http://wso2.org/claims/adusername | adusername | urn:mace:ucsd.edu:sso:ad:username |
| Network User ID | kerberos/network username | http://wso2.org/claims/networkuserid | networkuserid | urn:mace:ucsd.edu:sso:networkuserid |
| Department Codes | list of comma separated department codes in payroll | http://wso2.org/claims/departmentcodes | departmentcodes | urn:mace:ucsd.edu:sso:pps:departmentcodes |
| System ID | A persistent unique identifier for this user. This a GUID and is only relevant to the SOA set of services. Unlike all other identifiers, these will never be recycled and should be used as the user's primary ID in the remote system. | http://wso2.org/claims/systemid | systemid | urn:mace:ucsd.edu:sso:people:affiliateid |
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')
Resource Owner with Subscriber as Client Application Owner
{ "exp": 1449198389105,} |
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')
Resource Owner and BYU Entity as Client Application Owner
{ "exp": 1449196008421,} |
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')
No Resource Owner with Subscriber as Client Application Owner
{ "exp": 1449198083615,} |
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')
No Resource Owner and BYU Entity as Client Application Owner
{ "exp": 1449196866334,} |