Add a redirect URI to a login client

When you make an OpenID Connect (OIDC) authorization request, that request must include a redirect URI:

The redirect URI specifies the page that the user is sent to following a successful authentication. However, this doesn’t mean that you can redirect the user to just any old page. Instead, if you specify an invalid redirect URI in your authorization request you’ll be greeted with a suitably-appropriate error message and the Hosted Login sign-in screen will never be displayed:

Which leads to an obvious question: what makes one redirect URI valid and another redirect URI invalid?

And here's the answer to that question: valid redirect URIs are redirects specified in your OIDC login client. For example, by checking the value of the redirectURIs property we can see that client a123ef65-83dc-4094-a09a-76e1bec424e7 allows users to be redirected to any of four different pages:

{
   "id": "a123ef65-83dc-4094-a09a-76e1bec424e7",
   "name": "New Public Client",
    "redirectURIs": [
        "http://127.0.0.1",
        "https://localhost:3001/redirect_uri",
        "https://oidc-playground.akamai.com/redirect_uri",
        "https://openidconnect.net/callback"
    ],
    "loginPolicy": "ad2cad34-e06f-463e-a43f-b5c8af0ee965",
   "tokenPolicy": "a7f902b3-6e63-4f60-87a6-6cf5a1bc8ff4",
   "type": "public",
   "_links": {
       "self": {
           "href": "/config/e0a70b4f-1eef-4856-bcdb-f050fee66aae/clients/a123ef65-83dc-4094-a09a-76e1bec424e7"
       },
       "application_client": {
           "href": "/config/79y4mqf2rt3bxs378kw5479xdu/clients/u74hp2xa4u75dq9s6wv8yyb28wkkux7m"
      }
   }
}

In other words, as long as your authorization request includes one of those four URIs, you'll be in business.

And that's great ... provided that you want authenticated users redirected to one of those four locations. However, it's a good bet that you have some other page (or set of pages) that you'd rather redirect your users to. That means you'll need to add one or more URIs to the redirectURIs property. But how do you go about doing something like that?

The solution, as is often the case with Hosted Login, is to use the Identity Cloud’s OpenID Connect Configuration APIs. If you look at the properties and property values for an OIDC login client, (like we did a minute ago) you’ll spot a property named redirectURIs; fittingly enough, that property defines the URLs that can be used as a redirect location. For example:

"redirectURIs": [
       "http://127.0.0.1",
       "https://localhost:3001/redirect_uri",
       "https://oidc-playground.akamai.com/redirect_uri",
       "https://openidconnect.net/callback",
  ],
}

As you can see, the preceding client is configured with four redirect URIs. You say you want to add a fifth redirect location to this client? No problem; just use the /{customer_id}/config/clients/{oidcClientId} endpoint and the PUT method to add a fifth URL to the redirectURIs property:

"redirectURIs": [
       "http://127.0.0.1",
       "https://localhost:3001/redirect_uri",
       "https://oidc-playground.akamai.com/redirect_uri",
       "https://identitydocs.akamai.com/redirect_uri"
    ],
}

It’s as simple as that. Just make sure you enclose the URI in double quotes, and that you use proper JavaScript Object Notation (JSON) syntax.

📘

All URLs in the redirectURIs array must use the HTTPS protocol except http://127.0.0.1.

127.0.0.1 is the common IP address for localhost and is more secure than the localhost alias.

For those of you who use Curl, here’s what a full-fledged add-a-redirect-URI-to-a-login-client API call might look like:

curl -X PUT \
  'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/clients/a123ef65-83dc-4094-a09a-76e1bec424e7' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer bDyhs3ejty6Ea0-aw7hnxqOxmTXthqomLt8uiucdbVB7XkyiIh8DC9mm_4RRDZsC' \
  --data-raw '{
    "id": "a123ef65-83dc-4094-a09a-76e1bec424e7",
    "name": "New Public Client",
    "redirectURIs": [
        "http://127.0.0.1",
        "https://localhost:3001/redirect_uri",
        "https://oidc-playground.akamai.com/redirect_uri",
        "https://openidconnect.net/callback",
        "https://identitydocs.akamai.com/redirect_uri"
    ],
    "loginPolicy": "ad2cad34-e06f-463e-a43f-b5c8af0ee965",
    "tokenPolicy": "a7f902b3-6e63-4f60-87a6-6cf5a1bc8ff4",
    "type": "public"
}'

Two things to keep in mind when adding a redirect URI to an OIDC client. First, make sure you specify all the properties of the client and not just the redirect URI when making your API call. If you leave out a required property (like, say, the tokenPolicy) then your call will fail. If you leave out an optional property (like loginPolicy) then the new redirect URI will be added, but any of the property values you left out will be set to null. Did you forget to include loginPolicy? In that case, loginPolicy will be set to null, meaning the client no longer has a login policy. And without a login policy, that client can't be used for logins and registrations.

The best way to avoid problems like that is to first use the GET method to return all the current property values for the client. Copy and paste those existing values into the body parameter of your PUT call, and then add the new URI. This helps ensure that you don’t make an incomplete API call that you might regret later on.

Second, the redirectURIs property only accepts an array of redirect URIs; that means that you must surround your redirectURIs property value with square brackets ([ ]). This is true even if you only have a single redirect URI. Suppose, for example, that your API call uses this syntax:

"redirectURIs": "https://identitydocs.akamai.com/redirect_uri",

That’s going to result in the following error:

Instead, enclose your list of redirect URIs (even if there’s only one URI on that list) inside square brackets:

"redirectURIs": ["https://identitydocs.akamai.com/redirect_uri"],

Do that, and you’ll bypass that pesky Not a valid list! error.

Smart Redirect URIs

The wildcard %** can be appended to a domain or URL in the redirectURIs list to allow all URLs that begin with the preceding string.

This enables a single entry in the redirectURIs list to replace multiple entries that all begin with the same domain or URL.

For example, this:

"redirectURIs": [
        "http://127.0.0.1",
        "https://site.com",
        "https://site.com/login",
        "https://site.com/redirect_uri",
        "https://site.com/profile/redirect"
    ],

Can be replaced with this:

"redirectURIs": [
        "http://127.0.0.1",
        "https://site.com%**"
    ],