The Identity Cloud’s OpenID Connect Playground (https://oidc-playground.akamai.com) is a great way for organizations using Hosted Login to verify that their setup is up and running, and to test different authorization request options (for example, what happens if I set the prompt to login?). Did you just receive your new Hosted Login implementation and want to know if it’s actually working? Then do the following:

1. Go to https://oidc-playground.akamai.com, enter your Hosted Login login URL (which your Akamai representative provided to you) in the OpenID Connect URL field, and then click Next:

   

2. Enter the client ID for your OIDC public client (something else your Akamai representative gave you) in the OIDC Client ID field and then click Next:

   

3. Scroll to the bottom of the screen and click Start:

   

If the Hosted Login sign-in screen appears, you’re in business:

That’s all you have to do when it comes to the OpenID Connect Playground. As it turns out, however, there’s quite a bit more that you can do with the Playground: as we noted. the site provides a great way to experiment with Hosted Login and to gain a solid understanding of how Hosted Login works. Because of that, we’ve put together this guide, which explains the OpenID Connect Playground in detail. In addition, we’ve included a Hosted Login URL (https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login) and the client ID for an OpenID Connect public client (d0fb7483-46b1-43b6-b754-daba398380f2) that you can use to try these exercises out on your own. In other words, use the provided URL and client ID or use your own Hosted Login ID and client; it’s entirely up to you.

📘

With the sample Hosted Login site you can create and manage your own individual user account, and those accounts will be at least semi-permanent: if you create a user account today that account will probably still be available tomorrow. However, because this sample site is used for other testing purposes, we can’t guarantee that accounts will be available forever. If you return to the site and find that you can’t log in that probably means that your account was deleted, and you’ll have to create a new one. So it goes.

Before you begin

Before you can use the Identity Cloud OpenID Connect Playground to test a Hosted Login implementation, you’ll need to have the following information:

• The URL of the Identity Cloud OpenID Connect Playground ((https://oidc-playground.akamai.com)).
• The login URL for Hosted Login. If you want to try this yourself, and you don’t yet have your own Hosted Login implementation, you can use the URL https://v1.api.us.janrain.com/d0fb7483-46b1-43b6-b754-daba398380f2/login.
• The client ID for a public OpenID Connect client. For testing purposes, you can use the login URL shown above and the client ID d0fb7483-46b1-43b6-b754-daba398380f26.
• To fully test Hosted Login, you’ll also need to provide an email address and password and create an account on the test setup.

Testing Hosted Login

To test Hosted Login, start by pointing your web browser towards the OpenID Connect Playground: (https://oidc-playground.akamai.com). On the Playground home page, enter the login URL for your Hosted Login implementation in the Enter your OpenID Connect provider URL field and then click Next:

We might mention that there’s a bit of intelligence built into the Playground: if you enter an invalid URL your entry will be rejected. For example, if you enter (https://akamai.com) you’ll see this error:

The URL https://akamai.com fails because the Playground can’t connect to the discovery document associated with that URL (and that's because there is no discovery document associated with the URL) in order to download the required configuration information.

After you’ve entered a valid URL, enter the client ID of your OIDC public client in the field labeled Enter your public client ID and then click Next:

As it says onscreen, you must enter the client ID of a public client, an OIDC client that uses PKCE (Proof Key for Code Exchange) for authentication instead of a client secret (client secrets are used by confidential OIDC clients). The OpenID Connect Playground is designed to work only with public clients; in fact,, there's no way to enter a client secret when using the site.

📘

This isn’t some sort of limitation with the Playground: Akamai strongly recommends that you use public clients and PKCE for Hosted Login authentication. Using PKCE prevents you from needing to pass client secrets across the network, something especially important when working with cell phones and other devices that run on non-TLS networks.

We should also mention that the Playground has no way of knowing whether you’ve entered a valid client ID: that kind of information is known only to the authorization server and isn’t available to the Playground. That means the Playground can't tell you if a client ID is valid; instead, it assumes that pretty much anything you enter is a valid client ID:

And what happens if you do enter an invalid client ID? In that case, you'll see an error make your authentication request:

After entering your client ID you’ll come face-to-face with the Configure additional parameters section of the Playground. We’re not going to worry about this section right; we explain what those options are the article Optional authorization request parameters. With that in mind, ignore the Configure additional parameters section and click Next:

📘

OK, mostly skip over the Configure additional parameters section. Having told you to skip the section, you might want to take a look at the field labeled Scope, and note that the openid scope has been selected for you by default and can’t be unselected. That’s because this scope is required for all authorization requests that use OIDC.

Similarly, you can skip the Configure additional claims section (another section we discuss elsewhere) and then click Finish:

That’s all you have to configure. To make a Hosted Login authorization request, scroll down to the Authorize Call section and click Start in order to make an authorization request:

📘

If you prefer, you can copy the authorization request (click Copy), paste it into the address bar of your web browser, and then press ENTER. That results in the same behavior as clicking Start.

If everything goes according to plan (which it should), you’ll be presented with a sign-in screen:

But what if you don’t see the login dialog box, what if you see something that looks more like this:

This is the screen that you typically see following a successful login: if you’re seeing it now, that means you already have a valid Hosted Login session. Because of that, Hosted Login skipped the authentication process (after all, you’re already authenticated) and redirected you to the screen that displays session information.

So how can you “force” Hosted Login to actually make you log in? Well, when configuring your authentication request you can set the prompt parameter (found in the Configure additional parameters section we told you to skip) to login. If you do that, Hosted Login will always require you to log in, even if you already have a valid session running.

Because you just got your copy of Hosted Login, we’ll assume that you haven’t created any user accounts yet. If you do have an account, then go ahead and log in by entering your email address and password and then clicking Sign In.

📘

If you’re an administrator, you might think you already have an account; after all, how else could you log into Console and do things like modify API clients? But that’s different; that’s an administrator account. Here we’re talking about user accounts. To verify the user accounts that you do (or don’t) have, open Console, click Manage Profiles, then click the user entity type. If the search screen is empty you don’t have any user accounts yet.

If you don’t have an account, click Sign up for an account to display the registration dialog, fill out all the fields in the dialog and then click Create Account:

And now you should see this page:

If you do see that page, that means that everything went the way it was supposed to: your new account was created, you’ve been logged on, and you’ve been issued an access token, a refresh token, and an identity token.

But before you congratulate yourself and move on to bigger and better things, you might want to take a minute and examine the information found on this screen. This information is divided into the following sections:

• Making a token exchange call
• The Tokens section
• The ID Token section
• Making a userinfo call
• The userinfo section
• Accessing your user profile

Let’s take a closer look at each section.

Making a token exchange call

The OpenID Connect Playground uses an authorization code flow, generally considered the most secure OAuth authorization flow.

📘

Why is it considered the most secure flow? Well, for one thing the access token is not part of the redirect URL returned to the browser. That makes it more difficult for a hacker to intercept that token, and also ensures that the token won’t be stored in the browser history.

Using an authorization code flow means that, after a user has been authenticated, he or she doesn’t immediately receive an access token. Instead, the user is issued an authorization code, and that code must be exchanged for an access token (as well as a refresh token and an identity token). The Playground takes care of this exchange for you; that’s why you’ll see all your token information on this screen as well. For educational/informational purposes, however, the Playground does show you a curl version of the token exchange request:

Incidentally, there’s a Copy button associated with the token exchange call; clicking that button will copy the code to your clipboard. However, other than serving as a template for future token exchange requests, there isn’t much that you can do with that code. For example, here’s what happens if you open a command window and try running the copied code:

curl 'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/token' \
    -d 'grant_type=authorization_code' \
    -d 'code=livDhMcoja1_GSD2' \
    -d 'redirect_uri=https://oidc-playground.akamai.com/redirect_uri' \
    -d 'client_id=d0fb7483-46b1-43b6-b754-daba398380f2' \
    -d 'code_verifier=EBaGVQt3tNsqEMwvifM09ZjWSvKSMiZ7A32IAcdcgEQ' 

{"error":"invalid_grant","error_description":"code not found or expired"}

Note the error message: code not found or expired. Authorization codes can only be used once, and the Playground already used this code to return your tokens. Because of that, this code should fail. The system works!

The Tokens section

After a successful authentication your next step is to exchange your authorization code for a set of tokens. If the token exchange succeeds, you’ll be given the following:

• An access token. Access tokens are used to determine what you do, and do not, have access to.

• A refresh token. By default, access tokens are short-lived: they expire after just one hour. In theory, that means you need to reauthenticate every hour. In practice, however, you don’t have to reauthenticate every hour; that’s because you can use a refresh token to obtain a new access token. Because refresh tokens are valid for 90 days, a user can remain logged on for a long time before they finally have to reauthenticate.

• An identity token. Identity tokens are proof of your identity, and Hosted Login issues identity tokens following each successful authentication. Identity tokens provide a way to cache user information locally, but these tokens are never used for authorization purposes. That’s the job of an access token.

Information about all three of these token types is found in the Tokens section:

And yes, that’s interesting but, as a newcomer to Hosted Login, is there anything that you can do with these tokens other than look at them? As a matter of fact, there is. For example, if you this is your own site and you have administrator access, one thing you can do with the access token and the refresh token is send them to the introspection endpoint; that endpoint decodes the token and, among other things, lets you know whether or not the token is still valid.

You can call the introspection endpoint by using a curl command similar to the following:

curl -X POST \
  'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/token/introspect' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic ZGNiMjI0ZWEtYzNmNi00NmQ1LTljOTktY2M4ZDVjNGMyMmMwOjhfQWpLVXRWdG5fSWx0ZVRoTTFaV1BwYUlyVDdfWHg0cTh4cVFHbWZHNmxEck9aQVgtQjdpNjI1OC1INXRFa0p1MzV0ZEdmcTRIYXlRSHVmNndzQlln' \
  -d 'token=fYrol1RRulc9XSkubNAASgL3EH0pmnr6RVt9usWeV_f9IBvWMNjMtpXSl2zS4S74'

If the token is valid (i.e., the active property is true), you’ll get back information similar to this:

{
   "active": true,
   "scope": "openid",
   "client_id": "70a45721-c6ef-4d7c-91ff-f14e9346b8b6",
   "token_type": "Bearer",
   "exp": 1579886534,
   "iat": 1579882934,
   "sub": "b48f3a24-28e7-4f0b-8379-53f7d3ff6ec0",
   "aud": [
       "70a45721-c6ef-4d7c-91ff-f14e9346b8b6"
   ]
}

And if the token has expired (or isn’t a valid token in the first place), you’ll get back the following response:

{
   "active": false
}

And yes, that’s the only information you’ll get back: the token is invalid. Why is it invalid: has it expired, has it been revoked, is it using the wrong encoding? For security reasons, you’ll never know why it’s not a valid token. You’ll just know that it’s not.

Introspection is only for access tokens and refresh tokens; you can’t introspect an identity token. However, what you can do with an identity token is decode it. By default, identity tokens are Base64 encoded; that’s why your identity tokens look like this:

eyJhbGciOiJSUzI1NiIsImtpZCI6IjNhZjQ3ZTNmNmE0YmQwNTY5NzgyZmVlNWMxZjg2MjNhM2ZmMGQ3OGYiLCJ0eXAiOiJKV1Q
ifQ.eyJhdF9oYXNoIjoiYW9rZXFsWkRBcy1Yc3cwTmFUM3d3ZyIsImF1ZCI6WyI3MGE0NTcyMS1jNmVmLTRkN2MtOTFmZi1mMTR
lOTM0NmI4YjYiXSwiYXV0aF90aW1lIjoxNTc5ODgwOTM1LCJleHAiOjE1Nzk4ODc5NzEsImdsb2JhbF9zdWIiOiJjYXB0dXJlLXYxOi8
vc2UtZGVtb3MtZ3N0ZW1wLnVzLWRldi5qYW5yYWluY2FwdHVyZS5jb20vNzl5NG1xZjJydDNieHMzNzhrdzU0Nzl4ZHUvR1JFR
19ERU1PL2I0OGYzYTI0LTI4ZTctNGYwYi04Mzc5LTUzZjdkM2ZmNmVjMCIsImlhdCI6MTU3OTg4NDM3MSwiaXNzIjoiaHR0cHM6
Ly92MS5hcGkudXMuamFucmFpbi5jb20vZTBhNzBiNGYtMWVlZi00ODU2LWJjZGItZjA1MGZlZTY2YWFlL2xvZ2luIiwianRpIjoiMnl
BbnJKcGhjaEh3QXNXUWlLdVJMSUIwIiwic3ViIjoiYjQ4ZjNhMjQtMjhlNy00ZjBiLTgzNzktNTNmN2QzZmY2ZWMwIn0.j5Rnf6HqSK
7rpKo_iAw5D7Yrh21DafWnin7afJODvWS5fzBUws4C0RHqdh4dobVGXM7PcemKJNDervsP6jzygCsw4Ba4i5NciC1TQbdWx3JdX
rKFOiBCdlJhhU8G3onaBdKKPDk4DmrnVh5ChfmQshUDkOyNHVhlW9q5NpQHTAtSZJ9WUjxdUZ9oIN6L1J2j95nxYqNn_LeQBCa
CydDKNMK_PDzFveX0OcpqZUWgMzbmUDkOL06DlHLciXebC4Bv47yCD6fSIJwMYfQHgFk3vYkx9nzJgYXL5LJnu8fbqCbpU8W3
NCOjwCeYYl05kA3mX8IgeIQqqxBnk84jGw

That’s not exactly easy for human beings to read and to parse. Fortunately, there are tons of utilities on the Internet (both online utilities and command line utilities) that can decode JSON web tokens. For example, here we’ve copied the text for an identity token and pasted it into an online token decoder:

If you compare this output with the output shown in the ID Token section, they’ll be a perfect match.

The ID Token section

As noted in the previous section, the identity token is primarily used as a way to cache user information locally: doing that means you don’t have to make an API call to retrieve that data.

As you can see, however, by default an identity token doesn’t store a lot of useful information for a user:

The reason for that is simple: by default, OpenID Connect is very conservative when it comes to user information. As a general rule, if you want a specific piece of information about a user you have to ask for that information. OIDC doesn’t hand out user information (especially personally-identifiable info) as if it was candy.

Instead, you’ll need to create some standard (or custom) claims and add those claims to the identity token; we discuss that process in the article Return standard and custom claims. If you do that, then that user information will be available in the token itself. For example, here’s an excerpt from a token where the family_name and given_name claims have been added:

Making a Userinfo Call

As we mentioned, the identity token lets you cache user data on the client; that way the data is readily available without having to make a separate API call. That’s fast, and convenient, but it does mean that user data (and potentially personally-identifiable user data) is being stored locally.

If you’d rather not store user information locally, but would still like that information to be readily available, an alternative approach is to make it accessible from the userinfo endpoint. You’ll still have to make an API call to retrieve that information, but that only requires one simple API call:

📘

So what makes this API call simpler than other API calls (after all, you can always return user information by calling the /entity endpoint)? That’s true. However, that endpoint requires you to individually request each user profile attribute you want returned. (Otherwise you’ll get back the entire user profile, which could potentially be a lot of information.) By contrast, you don’t have to make specific requests when calling the userinfo endpoint: just make the call, and userinfo will return whatever user data you previously asked to be made available from there.

The curl command shown in the Userinfo call section works; if you want, you can click Copy to copy the command to the clipboard, then paste the command into a command window and run it:

curl 'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/profiles/oidc/userinfo' \
  -H 'Authorization: Bearer fYrol1RRulc9XSkubNAASgL3EH0pmnr6RVt9usWeV_f9IBvWMNjMtpXSl2zS4S74'

And what happens if your curl call succeeds? Well, at the risk of spoiling the next section of this documentation, you’ll get back something that looks like this:

{
   "global_sub": "capture-v1://se-demos-gstemp.us-dev.janraincapture.com/79y4mqf2rt3bxs378kw5479xdu/GREG_DEMO/b48f3a24-28e7-4f0b-8379-53f7d3ff6ec0",
   "sub": "b48f3a24-28e7-4f0b-8379-53f7d3ff6ec0"
}

The Userinfo Section

At first glance, the Userinfo section is, without question, the least interesting section on this page. After all, here’s what you see when you first look at this section:

How cool is that, huh?

Well, OK, maybe not all that cool. Fortunately, there’s more to Userinfo than meets the eye. This section is designed to display the return from a userinfo request. When you make an authentication request, you can specify which user profile attributes are automatically made available from the userinfo endpoint. Is that useful? You bet it is. All you have to do is make a call to the endpoint and you’ll get back all the user information stored there. It’s a very quick, very easy way to retrieve user information.

📘

User information for which user? When you call the userinfo endpoint, you need to pass a valid access token. Information is then returned for the user the token was issued to. Do you have a token for Maria Fuentes? Then you’ll get back all the information the userinfo endpoint has for Maria Fuentes.

Even better, you can call the userinfo endpoint (at least from the Playground) simply by clicking the big orange button :

Here’s the kind of information you’ll get back:

Admittedly, that might not be quite as exciting as we led you to expect. Why doesn’t the userinfo endpoint return something a bit more interesting? The main reason is that we didn’t ask it to return anything more interesting. By default, userinfo returns a minimal amount of information for each user. If you want anything more than that you’ll need to configure a standard or custom claim.

We won’t explain how to configure claims here; you can find that information in the article Return standard and custom claims . However, let’s assume that we’ve asked Hosted Login to make following claims available from userinfo: address, email, email_verified, family_name, and given_name. Now take a look at the info returned from a call to the userinfo endpoint:

That’s a little more like it.

Accessing Your User Profile

Another thing you can do from the OpenID Connect Playground is access your user profile (assuming, of course, that you’ve been authenticated and that you actually have a user profile). If you’re logged on, and if you’ve been issued an access token, you can type the following URL into your web browser and the press ENTER:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/profile?client_id=a123ef65-83dc-4094-a09a-76e1bec424e7

That should take you to your user profile:

This is a real user profile: you can enter and save data and, if you come back later, that data will still be there. For example, suppose your personal data looks like this:

Let’s further suppose that you change your display name from G. M. Stemp to Greg Stemp, and then log off. So what will you see the next time you log on? This:

Oh, and here’s another neat trick. You can also directly access the individual sections of your user profile by using these URLs:

• Personal Data: https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/profile/data?client_id=a123ef65-83dc-4094-a09a-76e1bec424e7
• Account Security: https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/profile/security?client_id=a123ef65-83dc-4094-a09a-76e1bec424e7
• Privacy Settings: https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/profile/privacy?client_id=a123ef65-83dc-4094-a09a-76e1bec424e7

Give them a try and see what happens.