SpheraCloud Services Guidance

Guidance and Best Practices Guides for our world class API's

Identity, Claims, & Tokens – An OpenID Connect Primer (part 3 of 3) #

What’s in a token? #

In the previous two parts of this OpenID Connect (OIDC) series, we dug deep into the OIDC flow types and saw OIDC in action using a playground found at: https://okta-oidc-fun.herokuapp.com/.

In this third and final part, we’ll look at what’s encoded into the various types of tokens and how to control what gets put in them. JWTs, have the benefit of being able to carry information in them. With this information available to your app you can easily enforce token expiration and reduce the number of API calls. Additionally, since they’re cryptographically signed, you can verify that they have not been tampered with.

There are two primary sources for information relating to identity as dictated by the OIDC spec. One source is the information encoded into the id_token JWT. Another is the response from the /userinfo endpoint, accessible using an access_token as a bearer token. At Sphera, we’ve chosen to make our access tokens JWTs as well, which provides a third source of information. (You’ll see this in many OIDC implementations.)

There are a lot of combinations of query parameters in the /authorization request that determine what information will be encoded into an id_token. The two query parameters that impact what will ultimately be found in returned tokens and the /userinfo endpoint are response_type and scope. See, this artlicle for an in-depth analysis of what parameters execute what behavior for openid and OAuth2.

OIDC Response Types #

For the moment, we’ll set aside scope and focus on response_type. In the following examples, we use only the scopes, openid (required) and email. We’ll also work with the implicit flow, since that gives us back tokens immediately.

Given this request:

https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/authorize?client_id=0oa2yrbf35Vcbom491t7&response_type=token&scope=openid+email&state=aboard-insect-fresh-smile&nonce=c96fa468-ca1b-46f0-8974-546f23f9ee6f&redirect_uri=https%3A%2F%2Finsight.spheracloud.com%2Fflow_result

Notice that response_type=token will yield us an access_token. A particular format is not required in the OIDC spec for access tokens, but at Sphera we use JWTs. Looking inside the returned token, we see:

{
	"active": true,
	"scope": "openid email",
	"username": "okta_oidc_fun@okta.com",
	"exp": 1501531801,
	"iat": 1501528201,
	"sub": "testuser@sphera.com",
	"aud": "test",
	"iss": "https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7",
	"jti": "AT.upPJqU-Ism6Fwt5Fpl8AhNAdoUeuMsEgJ_VxJ3WJ1hk",
	"token_type": "Bearer",
	"client_id": "0oa2yrbf35Vcbom491t7",
	"uid": "00u2yulup4eWbOttd1t7"
}

This is mainly resource information, including an expiration (exp) and a user id (uid).

If we want to get identity information for the user, we must hit the /userinfo endpoint using the access_token as a bearer token. Here’s what that looks like using HTTPie:

http https://micah.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/userinfo Authorization:"Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Ik93bFNJS3p3Mmt1Wk8zSmpnMW5Dc2RNelJhOEV1elY5emgyREl6X3RVRUkifQ..."
HTTP/1.1 200 OK
...
{
	"sub": "00u2yulup4eWbOttd1t7",
	"email": "okta_oidc_fun@okta.com",
	"email_verified": true
}

We get back the sub, email and email_verified claims. This is because of the default scope=openid+email from the original request. We’ll look at some more detailed responses in the scopes section.

Let’s try another request:

https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/authorize?client_id=0oa2yrbf35Vcbom491t7&response_type=id_token&scope=openid+email&state=aboard-insect-fresh-smile&nonce=c96fa468-ca1b-46f0-8974-546f23f9ee6f&redirect_uri=https%3A%2F%2Finsight.spheracloud.com%2Fflow_result

This time, I’m asking for an ID token by using response_type=id_token. The response is a JWT (as required by the OIDC spec) with this information encoded into it:

{
	"sub": "00u2yulup4eWbOttd1t7",
	"email": "testuser@sphera.com",
	"ver": 1,
	"iss": "https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7",
	"aud": "0oa2yrbf35Vcbom491t7",
	"iat": 1501528456,
	"exp": 1501532056,
	"jti": "ID.4Mmzy2kj5_B8nGZ_PT4dt8-fzu1tA2W3C5dbEF-N6Us",
	"amr": [
		"pwd"
	],
	"idp": "00o1zyyqo9bpRehCw1t7",
	"nonce": "c96fa468-ca1b-46f0-8974-546f23f9ee6f",
	"email_verified": true,
	"auth_time": 1501528157
}

Notice that we have the sub and email claims encoded directly in the JWT. In this type of implicit flow, we have no bearer token to use against the /userinfo endpoint, so the identity information is baked right into the JWT.

Finally, let’s look at the last type of implicit flow:

https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/authorize?client_id=0oa2yrbf35Vcbom491t7&response_type=id_token+token&scope=openid+email&state=aboard-insect-fresh-smile&nonce=c96fa468-ca1b-46f0-8974-546f23f9ee6f&redirect_uri=https%3A%2F%2Finsight.spheracloud.com%2Fflow_result

Here, we are requesting both an id_token and an access_token in the response.

Our access_token has the same claims as before. The id_token has the following:

{
	"sub": "00u2yulup4eWbOttd1t7",
	"email": "testuser@sphera.com",
	"ver": 1,
	"iss": "https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7",
	"aud": "0oa2yrbf35Vcbom491t7",
	"iat": 1501528536,
	"exp": 1501532136,
	"jti": "ID.fyybPizTmYLoQR20vlR7mpo8WTxB7JwkxplMQom-Kf8",
	"amr": [
		"pwd"
	],
	"idp": "00o1zyyqo9bpRehCw1t7",
	"nonce": "c96fa468-ca1b-46f0-8974-546f23f9ee6f",
	"auth_time": 1501528157,
	"at_hash": "T7ij7o69gBtjo6bAJvaVBQ"
}

Notice that there’s less information in the id_token this time (in this case, there’s no email_verified claim). Because we also requested the access_token, it’s expected that we will get the rest of the available identity information (based on scope) from the /userinfo endpoint. In this case, it yields the same information as before when we only requested the access_token

OIDC Scopes #

Combining all the available scopes with all the possible response types yields a large set of information to present: 48 combinations, to be exact. First, I’ll enumerate what each scope yields and then we’ll look at a few real world examples combining request_type and scope.

The first thing to note is that the different scopes have an impact on the information encoded in an id_token and returned from the /userinfo endpoint. Here’s a table of scopes and resultant claims. More information can be found in Section 5.4 of the OIDC Spec.

scope resultant claims
openid (required for all OIDC flows)
profile name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at
email email, email_verified
address address
phone phone_number, phone_number_verified

Let’s try each of our implicit flows with all the possible (default) scope types.

https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/authorize?client_id=0oa2yrbf35Vcbom491t7&response_type=token&scope=openid+profile+email+address+phone&state=aboard-insect-fresh-smile&nonce=c96fa468-ca1b-46f0-8974-546f23f9ee6f&redirect_uri=https%3A%2F%2Finsight.spheracloud.com%2Fflow_result

The only difference in the resultant access_token compared to before is that all the scopes are encoded into the scp array claim.

This time, when I use the access_token to hit the /userinfo endpoint, I get back more information:

http https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/userinfo Authorization:"Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Ik93bFNJS3p3Mmt1Wk8zSmpnMW5Dc2RNelJhOEV1elY5emgyREl6X3RVRUkifQ..."
HTTP/1.1 200 OK
...
{
	"sub": "00u2yulup4eWbOttd1t7",
	"name": "Test User",
	"locale": "en-US",
	"email": "testuser@sphera.com",
	"preferred_username": "testuser@sphera.com",
	"given_name": "Test User",
	"family_name": "User",
	"zoneinfo": "America/Chicago",
	"updated_at": 1499922371,
	"email_verified": true
}

Note: While it’s not the complete list of claims defined from profile scope, it’s all the claims for which my user, as defined in this system, has a value.

Let’s try just the id_token implicit flow (still with all the default scopes):

https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/authorize?client_id=0oa2yrbf35Vcbom491t7&response_type=id_token&scope=openid+profile+email+address+phone&state=aboard-insect-fresh-smile&nonce=c96fa468-ca1b-46f0-8974-546f23f9ee6f&redirect_uri=https%3A%2F%2Finsight.spheracloud.com%2Fflow_result

Here’s what’s encoded into the id_token I get back:

{
	"sub": "00u2yulup4eWbOttd1t7",
	"name": "Test User",
	"locale": "en-US",
	"email": "testuser@sphera.com",
	"ver": 1,
	"iss": "https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7",
	"aud": "0oa2yrbf35Vcbom491t7",
	"iat": 1501532222,
	"exp": 1501535822,
	"jti": "ID.Zx8EclaZmhSckGHOCRzOci2OaduksmERymi9-ad7ML4",
	"amr": [
		"pwd"
	],
	"idp": "00o1zyyqo9bpRehCw1t7",
	"nonce": "c96fa468-ca1b-46f0-8974-546f23f9ee6f",
	"preferred_username": "testuser@sphera.com",
	"given_name": "Test",
	"family_name": "User",
	"zoneinfo": "America/Chicago",
	"updated_at": 1499922371,
	"email_verified": true,
	"auth_time": 1501528157
}

All the (available) identity information is encoded right into the token, since I don’t have a bearer token to hit the /userinfo endpoint with.

Finally, let’s try the last variant of the Implicit Flow: response_type=id_token+token:

https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/authorize?client_id=0oa2yrbf35Vcbom491t7&response_type=code+id_token+token&scope=openid+profile+email+address+phone&state=aboard-insect-fresh-smile&nonce=c96fa468-ca1b-46f0-8974-546f23f9ee6f&redirect_uri=https%3A%2F%2Finsight.spheracloud.com%2Fflow_result

In this case, we have some of the claims encoded into the id_token:

{
	"sub": "00u2yulup4eWbOttd1t7",
	"name": "Test User",
	"email": "testuser@sphera.com",
	"ver": 1,
	"iss": "https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7",
	"aud": "0oa2yrbf35Vcbom491t7",
	"iat": 1501532304,
	"exp": 1501535904,
	"jti": "ID.1C2NQext2hM0iJy55cLc_Ryc45urVYC1wJ0S-KebkpI",
	"amr": [
		"pwd"
	],
	"idp": "00o1zyyqo9bpRehCw1t7",
	"nonce": "c96fa468-ca1b-46f0-8974-546f23f9ee6f",
	"preferred_username": "testuser@sphera.com",
	"auth_time": 1501528157,
	"at_hash": "GB5O9CpSSOUSfVZ9CRekRg",
	"c_hash": "mRNStYQm-QU4rwcfv88VKA"
}

If we use the resultant access_token to hit the /userinfo endpoint, in this case, we get back:

http https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/userinfo Authorization:"Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Ik93bFNJS3p3Mmt1Wk8zSmpnMW5Dc2RNelJhOEV1elY5emgyREl6X3RVRUkifQ..."
HTTP/1.1 200 OK
...
{
	"sub": "00u2yulup4eWbOttd1t7",
	"name": "Test User",
	"locale": "en-US",
	"email": "testuser@sphera.com",
	"preferred_username": "testuser@sphera.com",
	"given_name": "Test",
	"family_name": "User",
	"zoneinfo": "America/Chicago",
	"updated_at": 1499922371,
	"email_verified": true
}

This rounds out all the identity information that was requested in the scopes.

Custom Scopes and Claims #

The OIDC spec accommodate custom scopes and claims. The ability to include custom claims in a token (which is cryptographically verifiable) is an important capability for identity providers. Sphera’s implementation provides support for this.

The screenshot below shows the Sphera B2C Server’s Claims tab:

custom claims

Clicking the “Add” (+) button brings up a dialog:

new claim

In the above screenshot, the custom claim is defined using Azure B2C.

Using the implicit flow with response_type=id_token and scope=openid+profile, we now get back an id_token with these claims encoded in it:

{
	"sub": "00u2yulup4eWbOttd1t7",
	"ver": 1,
	"iss": "https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7",
	"aud": "0oa2yrbf35Vcbom491t7",
	"iat": 1501533536,
	"exp": 1501537136,
	"jti": "ID.TsKlBQfGmiJcl2X3EuhzyyLfmzqi0OCd66rJ3Onk7FI",
	"amr": [
		"pwd"
	],
	"idp": "00o1zyyqo9bpRehCw1t7",
	"nonce": "c96fa468-ca1b-46f0-8974-546f23f9ee6f",
	"auth_time": 1501528157,
	"at_hash": "hEjyn3mbKjuWanuSAF-z4Q",
	"NewClaim": "Some value"
}

Notice the NewClaim claim present in the id_token.

Verifying Tokens #

Access tokens can be verified by hitting the /introspect endpoint. For an active token, you get a response like this:

http --auth <OIDC Client ID>:<OIDC Client Secret> -f POST \
https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/introspect \
token=eyJhbGciOiJSUzI1NiIsImtpZCI6Ik93bFNJS3p3Mmt1Wk8zSmpnMW5Dc2RNelJhOEV1elY5emgyREl6X3RVRUkifQ...
HTTP/1.1 200 OK
...

{
    "active": true,
    "aud": "https://insight.spheracloud.com",
    "client_id": "xdgqP32nYN148gn3gJsW",
    "exp": 1498517509,
    "fullName": "Test User",
    "iat": 1498513909,
    "iss": "https://sphera.oktapreview.com/oauth2/aus9vmork8ww5twZg0h7",
    "jti": "AT.JdXQPAuh-JTqhspCL8nLe2WgbfjcK_-jmlp7zwaYttE",
    "scope": "openid profile",
    "sub": "00u9vme99nxudvxZA0h7",
    "token_type": "Bearer",
    "uid": "00u9vme99nxudvxZA0h7",
    "username": "testuser@sphera.com"
}

Since it requires the OIDC client ID and secret, this operation would typically be done in an application server where it’s safe to have those credentials. You would not want something like an end-user web or mobile application to have access to the OIDC client secret.

If the token parameter is invalid or expired, the /introspect endpoint returns this:

http --auth <OIDC Client ID>:<OIDC Client Secret> -f POST \
https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/introspect \
token=bogus
HTTP/1.1 200 OK
...
{
    "active": false
}

ID tokens can be verified using the JWK endpoint. JWK is a JSON data structure that represents a crypto key. The JWK endpoint is exposed from the OIDC “well known” endpoint used for API discovery. This returns a lot of information. Here’s an excerpt:

http https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/.well-known/openid-configuration
HTTP/1.1 200 OK
...
{
    "authorization_endpoint": "https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/authorize",
	...
    "introspection_endpoint": "https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/introspect",
	...
    "issuer": "https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7",
    "jwks_uri": "https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/keys",
	...
    "userinfo_endpoint": "https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/userinfo"
}
Some of the endpoints, such as /userinfo and /authorize, should look familiar by now. The one we’re interested in is the /keys endpoint shown in jwks_uri.

http https://sphera.okta.com/oauth2/aus2yrcz7aMrmDAKZ1t7/v1/keys
HTTP/1.1 200 OK
...
{
    "keys": [
        {
            "alg": "RS256",
            "e": "AQAB",
            "kid": "cbkhWG0YmFsGiNO1LEkWSEszDCTNfwvJPpXxuVf_kX0",
            "kty": "RSA",
            "n": "g2XQgdyc5P6F4K26ioKiUzrdgfy90eBgIbcrKkspKZmzRJ3CIssv69f1ClJvT784J-...",
            "use": "sig"
        }
    ]
}

Notice the kid claim. It matches the kid claim in the header from our id_token:

{
 "typ": "JWT",
 "alg": "RS256",
 "kid": "cbkhWG0YmFsGiNO1LEkWSEszDCTNfwvJPpXxuVf_kX0"
}

We can also see that the algorithm used is RS256. Using the public key found in the n claim along with a security library, we can confirm that the ID token has not been tampered with. All of this can be done safely on an end-user SPA, mobile app, etc.

If any part of the id_token JWT had been tampered with, you would see this instead:

io.jsonwebtoken.SignatureException: JWT signature does not match locally computed signature. JWT validity cannot be asserted and should not be trusted.

Verifying JWT’s using the /introspect endpoint and using JWKs is a powerful component of OIDC. It allows for a high degree of confidence that the token has not been tampered in any way. And, because of that, information contained within – such as expiration – can be safely enforced.

How I Learned to Love OpenID Connect #

When OIDC was first released and early implementers, such as Google, adopted it, we all thought: “I just got used to OAuth 2.0. Why do I have to learn a new thing that rides on top of it?”

It took some time, but here is what I consider to be the important takeaways:

  • OIDC formalizes a number of things left open in OAuth 2.0. Things like: specific token formats (id_token) and specific scopes and claims.
  • There’s explicit support for Authentication and Authorization. OAuth 2.0 was always presented purely as an authorization framework, but people would get confused with certain flows that allowed for authentication.
  • There’s a clear separation between identity (id_token and /userinfo) and access to resources (access_token).
  • The different flows provide clean use case implementations for mobile apps, SPAs, and traditional web apps.
  • It’s inherently flexible. It’s easy to provide custom scopes and claims and to dictate what information should be encoded into tokens beyond the default specification.