How to Integrate an Access Control System with Schlage Mobile Credentials Solution

NFC Mobile Credential ID Token and Access Token Requirements

Last modified: 03.01.2024

Schlage's NFC Mobile Credential systems identify and authorize users and access rights using JSON Web Tokens, or JWTs (typically pronounced as "jots"). JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs are credentials, identifying an entity and providing information about that entity. JWTs allow companies and systems to securely share identity about users, applications and objects in a standard way.

JWTs allow a company to identify mobile credentials users and provide Allegion with a mechanism to verify the identity and authorization of a user based on information contained within a JWT. For use with Schlage Mobile Credentials, JWTs allow companies to share identity and authorization of a given user with regard to their ability to use a mobile application to download and use a mobile credential on their mobile phone.

Schlage NFC Mobile Credentials uses two standard types of JWTs to authorize users and applications:

ID Tokens - ID Tokens are used to identify a user. ID token represent a user's identity. Allegion relies on ID token JWTs provided by a mobile application to validate a user's identity.

Note: While Allegion does not explicitly rely on the Open ID Connect standard for definition of ID Tokens, it conforms closely an can be used as a standard to follow for generating JWTs.

Access Tokens - Access Tokens are used to specify a user's access privileges to a given resource such as an application. Allegion relies on Access token JWTs to verify that a user identified by the token has authorization to use Schlage Mobile Credentials system resources to do things such as making requests to download mobile credentials to their phone.

Note: While Allegion does not explicitly rely on the OAuth2.0 standard for definition of Access Tokens, it conforms closely an can be used as a standard to follow for generating JWTs.

More on the difference between ID Tokens and Access Tokens is covered here.

The remainder of this document will cover the details of required claims for ID and Access Tokens.

ID Token Claims

Claim	Description	Required
`sub`	The sub (subject) of the JWT. This value represents the user’s id from the access control system used to create the mobile credential. This should be provided in GUID format.	Yes
`iss`	The iss (issuer) claim identifies who created and signed this JWT. For the ID Token, this claim must be present but the value is not actually validated by Allegion.	Yes
`nbf`	The nbf (not valid before) claim identifies the time at which this JWT becomes valid. The processing of the nbf claim requires that the current date/time MUST be after the date/time listed in the nbf claim.	Yes
`exp`	The exp (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The processing of the exp claim requires that the current date/time MUST be before the expiration date/time listed in the exp claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a NumericDate value.	Yes
`aud`	The aud (audience) claim represents the target recipient for which the JWT is intended. The value of this claim must be `AllegionAccessHub` for Allegion Mobile Credentials integration.	Yes
`iat`	The iat (issued at) claim identifies the time at which the JWT was issued.	No

Example ID Token

{
    "sub": "92503ea1-9bd0-451d-a937-b8ed43f6c9e0",
    "nbf": 1653492910,
    "exp": 2145938400,
    "iat": 1653492910,
    "iss": "https://my-company.io",
    "aud": "AllegionAccessHub"
}

Access Token Claims

Claim	Description	Required
`sub`	The sub (subject) of the JWT. This value represents the user’s id from the access control system used to create the mobile credential. This should be provided in GUID format.	Yes
`iss`	The iss (issuer) claim identifies who created and signed this JWT. For the Access Token, the value of this claim is determined and agreed to between the partner and Allegion during development/planning, and Allegion will validate that the value is present and accurate for each JWT it receives.	Yes
`nbf`	The nbf (not valid before) claim identifies the time at which this JWT becomes valid. The processing of the nbf claim requires that the current date/time MUST be after the date/time listed in the nbf claim.	Yes
`exp`	The exp (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The processing of the exp claim requires that the current date/time MUST be before the expiration date/time listed in the exp claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a NumericDate value.	Yes
`aud`	The aud (audience) claim represents the target recipient for which the JWT is intended. The value of this claim depends on the implementation you are completing. For Employee Badge Mobile Credential implementation, the value of this claim should be: `https://api.allegion.com/employeebadge` For Resident Key Mobile Credential implementation, the value of this claim should be: `https://api.allegion.com/residentkey` For Student ID Mobile Credential implementation, the value of this claim should be: `https://api.allegion.com/studentid`	Yes
`iat`	The iat (issued at) claim identifies the time at which the JWT was issued.	No
`https://api.allegion.com/email`	This is a custom claim used to convey the user's email address to Allegion. The value of this claim is used to correlate the user attempting to use the mobile credential app with a user known to the access control system based on the same email as having authorization to use the app for the purpose of downloading a mobile credential. As such, the email address used here must match an email address used to create an access right for this user.	Yes

Example Access Token

{
    "sub": "92503ea1-9bd0-451d-a937-b8ed43f6c9e0",
    "nbf": 1653492910,
    "exp": 2145938400,
    "iat": 1653492910,
    "iss": "https://my-company.io",
    "aud": "https://api.allegion.com/employeebadge",
    "https://api.allegion.com/email": "jane.user@gmail.com"
}