🧬 Introduction
As mentioned in the previous article, the main difference between OAuth2.0 and OIDC is that in OIDC you are passing openid as a scope and you are getting an ID Token due to that.
This ID Token is a security token that contains Claims about the Authentication of an end-user by an Authorization Server when using a Client, and potentially other requested Claims. The ID Token is represented as a JSON Web Token (JWT).
📦 JWT
JWT or JSON Web Token is an open standard 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 can be signed using a secret(with HMAC algorithm) or a public/private key pair using RSA or ECDSA.
In its compact form, JSON Web Tokens consist of three parts separated by dots(.), which are:
Header
Payload
Signature
Therefore a JWT typically looks like this, xxxxx.yyyyy.zzzzz
🤯 Header
The header typically consists of two parts: the type of the token, which is JWT, and the signing algorithm being used, such as HMAC SHA256, or RSA.
{
"alg": "HS256",
"typ": "JWT"
}
Then this JSON is Base64URL encoded to form the first part of the JWT.
📑 Payload
The second part of the token is the payload, which contains the claims. Claims are statements about an entity(typically, the user) and additional data. There are three types of claims: registered, public, and private claims.
📙 Registered Claims
These are a set of predefined claims which are not mandatory but recommended, to provide a set of useful, interoperable claims. Some of them are iss(issuer), exp(expiration time), sub(subject), and aud(audience).
📗 Public Claims
These can be defined at will by those using JWTs. But to avoid collisions they should be defined in the IANA JSON Web Token Registry or be defined as a URI that contains a collision-resistant namespace.
📕 Private Claims
These are the custom claims created to share information between parties that agree to use them and are neither registered nor public claims.
{
"sub": "1234567890",
"name": "WSO2 IS",
"admin": true
}
The payload is then Base64URL encoded to form the second part of the JWT.
✍🏻 Signature
To create a signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that.
For example, if you want to use the HMAC SHA256 algorithm, the signature will be created in the following way.
HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
secret)
The signature is used to verify the message wasn't changed along the way, and in the case of tokens signed with private keys, it can also verify the sender of the JWT is who it says it is.
📌 Using JWT as the ID Token
According to the OIDC specification, the ID Token, which is a JWT can have the following claims.
iss - Issuer identifier for the issuer of the response. This is a case-sensitive URL using the
httpsscheme that contains scheme, host, and optionally, port number and path components, and no query or fragment components. This is a required claim in OIDC.sub - Subject Identifier. A locally unique and never re-assigned identifier within the issuer for the end-user, which is intended to be consumed by the Client. It must not exceed 255 ASCII characters in length. This is a case-sensitive string and a required claim in OIDC.
aud - Audience(s) that this ID Token is intended for. It must contain the OAuth2.0 Client ID of the relying party as an audience value. It may also contain identifiers for other audiences. This is a required claim in OIDC.
exp - Expiration time on or after which the ID Token must not be accepted by the Client (or the Relying Party as mentioned in the OIDC spec.)when performing authentication with the OpenID Provider(OP, When an Authorization Server supports OIDC, it is sometimes called an Identity Provider). This is a required claim in OIDC.
iat - Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time. This is a required claim in OIDC.
auth_time - Time when the end-user authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time. When a
max_agerequest is made or whenauth_timeis requested as an essential Claim, then this Claim is required; otherwise, its inclusion is optional.nonce - String value used to associate a Client session with an ID Token, and to mitigate replay attacks. This value is passed through unmodified from the authentication request to the ID Token. If present in the ID Token, clients must verify the
nonceclaim value is equal to the value of thenonceparameter sent in the authentication request. If present in the authentication request, authorization servers must include anonceclaim in the ID Token.acr - Authentication context class reference. A string specifying an authentication context class reference value that identifies the authentication context class that the authentication performed satisfied. This is an optional claim in OIDC.
amr - Authentication methods references. JSON array of strings that are identifiers for authentication methods used in the authentication. For instance, values might indicate that both password and OTP authentication methods were used. This is an optional claim in OIDC.
azp - Authorized party - the party to which the ID Token was issued. If present, it must contain the OAuth2.0 Client ID of this party. This is an optional claim in OIDC.
To parse a JWT and know what are the claims associated with it, you can use the https://jwt.io website.
In the next article, we will be discussing OIDC Dynamic Client Registration and how you can use WSO2 IS DCR API to achieve dynamic client registration.