SuperOffice Online Open ID Connect

Vurderinger

Introduction to OpenID Connect

Open ID Connect is a thin layer that sits on top of the oauth 2.0 protocol. It enables clients to verify the identity of the end-user based on the authentication performed by an authorization server. OpenID Connect is needed because even though OAuth provides authorization it doesn’t provide authentication.

OpenID Connect

With OAuth the authenticated user proved they were present to the authorization server, but the sole purpose of this was to create and grant an access token to the client application.

The user does not authenticate directly with an online application itself. OAuth is limited in that it provides a type of pseudo authentication. It provides temporary access to resources rather than information about the authentication itself. It does not provide the when, where and how the authentication actually occurred, and it doesn’t allow federated single sign on, either.

OpenID Connect extends OAuth so online applications can get identity information, retrieve details about the authentication event, and allow federated single sign on.

To understand how OpenID Connect works, we’ll review basic concepts such as Participants, Identity Tokens, Claims and Scopes, and Endpoints. Let’s first look at the participants.

The End User is the tenant user for whom we are requesting identity information. In OAuth 2.0 this refers to the resource owner and one of the resources they own is their own identity.

The Relying Party is an OAuth 2.0 client, or partner application, that relies on the Identity Provider to authenticate users and request claims about that user.

The Identity Provider is an OAuth 2.0 authorization server, such as SuperOffice SuperID, which offers authentication as a service. It ensures the End-User is authenticated and provides claims about the End-User and the authentication event to the Relying Party.

Identity Tokens and Claims

So how does the Identity Provider provide the Relying Party information about the identity of the End User? The answer is through an Identity Token. The Identity Token is similar to an ID card or passport. It contains a number of required attributes or claims about that End User, including how the End-User was authenticated. These claims are: Subject, Issuing Authority, Audience, Issue Date and Expiration Date.

The Subject is a unique identifier assigned to a user by the Identity provider, for example a username. The Issuing Authority is the Identity Provider that issued the token. The Audience identifies the Relying Party, or partner application, that can use the token. The Issue and Expiration Date is the date and time the token was issued and will expire, respectively.

There are also a number of optional claims that help the Relying Party validate the ID Token, such as authentication time which shows the time the End-User was authenticated and Nonce values which mitigate replay attacks.

As with access tokens, the ID Token is encoded as a JSON Web Token or JWT, which consists of a Header, Payload and Signature. These elements are delimited by a period. The claims in the token form part of the payload.

ID Token

OpenID Connect uses claims to retrieve information, but it can also use scopes. The OpenID Connect specification contains around 20 standard claims and four standard scopes, which are used to supply the client application with consented user details. SuperOffice Online only supports one scope: openid, but includes additional claims normally obtained at the UserInfo endpoint, such as first name, last name and email address.

SuperOffice Claims

Claim Name Federated Id OpenID Connect Description
aud X X The service principal name (spn) claim identifier followed by the tenant database serial number.
exp X X Expiration time on or after which the ID Token MUST NOT be accepted for processing.
c_hash   X Code hash value.
iat   X Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
iss X X Issuer Identifier for the Issuer of the response. Options: SuperOffice AS (Federated ID), https://sod.superoffice.com (OpenID Connect)
nbf X X The time before which the JWT MUST NOT be accepted for processing.
nonce   X A string used to associate a Client session with an ID Token, and to mitigate replay attacks.
sub X X Subject Identifier. Always same as claim: http://schemes.superoffice.net/identity/upn
http://schemes.superoffice.net/identity/
associateid
X X The current users associate Id.
http://schemes.superoffice.net/identity/
company_name
X   The current users company name.
http://schemes.superoffice.net/identity/
ctx
X X The tenent identifier.
http://schemes.superoffice.net/identity/
email
X X The current users email address.
http://schemes.superoffice.net/identity/
firstname
X X The current users first name.
http://schemes.superoffice.net/identity/
identityprovider
X X The identity provider responsible for authentication. Options: central-superid, superoffice-online (federated Id) or google (federated Id).
http://schemes.superoffice.net/identity/
initials
X X The current users full name initials. (added June 2019)
http://schemes.superoffice.net/identity/
is_administrator
X X Determine whether current user is an administrator.
http://schemes.superoffice.net/identity/
lastname
X X The current users last name.
http://schemes.superoffice.net/identity/
netserver_url
X X The URL to a tenant SOAP web services. Often used in conjunction with SuperOffice .NET nuget proxies. New apps should always use the latest, which as of this writing (June2019) is Services86.
http://schemes.superoffice.net/identity/
remember_me_expires
X X Not used.
http://schemes.superoffice.net/identity/
serial
X X The tenant database serial number.
http://schemes.superoffice.net/identity/
so_primary_email_address
X X The current users primary email address. (added June 2019)
http://schemes.superoffice.net/identity/
system_token
X X A unique identifier, used to exchange for a system ticket. Used for background processing, back channel communications.
http://schemes.superoffice.net/identity/
ticket
X   A current users unique identifier, used for authentication.
http://schemes.superoffice.net/identity/
upn
X X Specifies a user principal name (UPN).
http://schemes.superoffice.net/identity/
webapi_url
X X The URL to a tenant REST web services.

 

Code Example:

JWT Claims

 

The OpenID Connect identity provider has a number of end points with which the end-user and client application interact. SuperOffice Online supports the Authorization Endpoint and the Token Endpoint. The UserInfo endpoint is not supported at the time of this article.

The Authorization endpoint is where the End-User is asked to authenticate and grant the partner application consent to access their identity. Once consent is given, this endpoint passes back an authorization code. This endpoint is where the End-User indirectly interacts with the Identity Provider through a user agent, such as a browser.

The Token endpoint authenticates the client application. It also exchanges the authorization code from the authorization endpoint for an ID token, an access token and refresh token.

OpenID Connect metadata document

OpenID Connect describes a metadata document that contains most of the information required for an app to perform sign-in. This includes information such as the URLs to use and the location of the service’s public signing keys. The OpenID Connect metadata document can be found at:

https://{environment}.superoffice.com/login/.well-known/openid-configuration

The environment subdomain is unique for each application environment; development (sod), stage (qaonline) and production (online).

The metadata is a simple JavaScript Object Notation (JSON) document. See the following snippet for an example.

{
"issuer": "https://sod.superoffice.com",
"authorization_endpoint": "https://sod.superoffice.com/login/common/oauth/authorize",
"token_endpoint": "https://sod.superoffice.com/login/common/oauth/tokens",
"jwks_uri": "https://sod.superoffice.com/login/.well-known/jwks",
"scopes_supported": [
  "openid"
],
"response_modes_supported": [
  "form_post",
  "fragment",
  "query"
],
"response_types_supported": [
  "code",
  "id_token",
  "code id_token",
  "token id_token",
  "token"
],
"subject_types_supported": [
  "public"
],
"id_token_signing_alg_values_supported": [
  "RS256"
],
"token_endpoint_auth_methods_supported": [
  "client_secret_post",
  "client_secret_basic"
],
"grant_types_supported": [
  "implicit",
  "authorization_code",
  "refresh_token"
],
}

OpenID Connect Flows

Now let’s look at the authentication flows available in OpenID Connect, and how id tokens and user information are exchanged.

OpenID Connect defines three authentication flows:

  1. Authorization Code flow
  2. Implicit flow
  3. Hybrid flow.

The Authorization Code and Implicit flows are based on the OAuth flows of the same name. The main difference with OpenID Connect is that an ID token is also issued. As these OpenID Connect flows are based on the same OAuth flows, the types of applications they are best suited for are also the same.

The Hybrid flow is a combination of the Authorization Code and Implicit flow. In this flow the client can request ID tokens, access tokens, or both from the Authorization endpoint, along with an Authorization code that can be exchanged at the token endpoint for the remaining tokens. It’s useful in situations such as single sign on, for example, where the partner application needs to immediate use an identity token to access the user’s identity. It also uses an authorization code to request access, and refresh tokens to get long-lived access to resources.

The Hybrid Flow offers more flexibility with this token flow, but it’s less secure than the Authorization Code Flow because some tokens are exposed directly to the User Agent. Let’s now look at these flows in more detail.


Authorization Code Flow

In the Authorization code flow, an end user accesses a client application that requires the user to authenticate. After clicking login, the partner application redirects the user agent, typically a browser, to the authorization endpoint of the Identity Provider.

There are two types of Authorization Code Flow. The standard as described below, and Proof Key for Code Exchange (PKCE) to support native applications such as Windows apps and mobile phone apps. PKCE support was introduced in January 2020.

https://sod.superoffice.com/login/common/oauth/authorize

The user agent makes a request to the Identity Provider authorization URI with the following information:

  1. a Response Type set to code, which indicates this is the authorization code flow.
  2. the scope set to openID. The Scope openID shows this is a request for OpenID Connect authentication and an ID token.
  3. the Client ID of the relying party, or partner application, registered with the Identity Provider.
  4. the state, which is a value set by the relying to maintain state between the request and the callback itself.
  5. the Redirect URI, which is the location to redirect the callback to once authenticated.
GET Request (test in a browser to handle the login/redirect)

https://sod.superoffice.com/login/common/oauth/authorize?
client_id=c789b7d98f3c496fb5aaa4b1a81ca11b&
scope=openid&
redirect_uri=https://partnerapp/callback&
state=12345&
response_type=code&
Parameter Description
client_id Required. The Application Id assigned to your app when you registered it with SuperOffice.
scope Required. Must be openid.
redirect_uri Required. The redirect_uri of your app, where authentication responses are sent and received by your app. It must exactly match one of the redirect_uris registered with SuperOffice.
state Recommended. A value included in the request that is also returned in the token response.
response_type Required. Must include code for the authorization code flow.
response_mode Optional. Can be fragment and returns parameters in URI after hash #,or form_post and returns values in form data.
login_hint Optional. Hint to the Authorization Server about the login identifier the End-User might use to log in. For SuperOffice, this must be SuperID username. When used, it updates the user name in the login cookie and is displayed in the username field. (added June 2019)
code_challenge Required for PKCE only. (added January 2020)
code_challenge_method Optional for PKCE only. Defaults to "plain" if not present in the request. Code verifier transformation method is "S256" or "plain". (added January 2020)

The user is then directed to the authentication server login screen, where they enter their credentials. An Identity Provider authenticates the user and asks for consent to access their resources on behalf of the Relying Party.

With consent given, the authentication server sends an authorization response message from its authorization endpoint. This redirects the user agent back to the relying party using the redirection URI provided earlier. This URI includes an authorization code and any state provided by the client earlier.

GET Response

https://partnerapp/callback?
state=12345&
code=o0NWI5leHdUflrjlTVVKqbSOt3n9Od0ZrBUq0nXFWKszyOdOZchk60fTf4pDWTFT
Parameter Description
code The authorization code generated by the,authorization server.,The authorization code expires after 10 minutes.
state The exact value received from the client.

The relying party then makes a request for an ID token to the token endpoint by sending the client ID, client secret, the Authorization code, the redirect URI and the Grant Type.

POST Request (can be tested in a client such as Postman or Fiddler)
Content-Type: application/x-www-form-urlencoded https://sod.superoffice.com/login/common/oauth/tokens? client_id=c789b7d98f3c496fb5aaa4b1a81ca11b& client_secret=83d0f3bcb9afbc7eb9d0682e9b86db52& code=o0NWI5leHdUflrjlTVVKqbSOt3n9Od0ZrBUq0nXFWKszyOdOZchk60fTf4pDWTFT& redirect_uri=http://partner-app/callback& grant_type=authorization_code&
Parameter Description
client_id Required. The Application Id assigned to your app when you registered it with SuperOffice.
client_secret Required, except when using PKCE. The Application Token assigned to your app when you registered it with SuperOffice.
code Required. The authorization code that the application requested. The application can use the authorization code to request an access token for the target resource.
redirect_uri Required. The redirect_uri of your app, where authentication responses are sent and received by your app. It must exactly match one of the redirect_uris registered with SuperOffice.
grant_type Required. Must be authorization_code for the authorization code flow.
code_verifier Required for PKCE only. (added January 2020)

The Identity provider authenticates the client using the client ID and secret, and validates the redirect URI. When the grant type is set to authorization_code, the identity provider will validate the code parameter. Alternatively, the grant_type is set to refresh_token and the provider will validate the refresh_token parameter.

If valid, the Identity Provider responds back with the ID token from the token endpoint. The response also includes an access token and an optional refresh token. The client validates the ID token, and if successful, the identity is proven and the Authorization Code flow is complete.

POST Response

{
"token_type": "Bearer",
"access_token": "8A:Cust12020.AR2s3phb0gXK8DP0NfoYlsrQAQAACIJ/KQ+cbGp0l9g8PJNlBCEZxS/1hL3Cxt8ITWlQipRbdt5CL1lQmUotYHaQQH9/Y7nq98WduG7QuSY7KMiSQRxHn7W5qppkEjlSTLW2+xfaV42eL2Vvw6V2WVwICzP6iE6wUDv/VX8Zgbp757BdKY4mIRnxsaGtpFGBFwKASLiLJ69SoUnYz753mx6XCwTFtgZRywCKDwykXLFoQ5qgAbhCkxs7IFmcBszRIgAAdul49zG/iAho24yw6fgcz/J+TpxVE/CpSsXsdDV/JpSA96ny9SQQ97t8HeRvCG5F/uUdE8TvzKorwIbccEvAGbsjRNsH0iKCP1BsnPUIRdq6f3iQf2R+LVEN1XqvxE7JsbF9cYwQ0IWtW3hfFy8BanBvqbYFYQcHLC3Qq/KTIJF8jZeV0djYoM8fzVY/hkLavIKWHXQnVWU7Vw/yTWHpuX+5xUTjJbHEhyduDImLNvOCPXzRQpQgso7agBMUEHzTXyTE348g1OZA32SfnAWwXMh/AvLZ1IQ0m5rzRcM1g3AolEmJWm3+2wPY5pmV6D6N3JTGgUA+b6USonaknTbIFxUuUChHj4U1qUlP6/dJA+aKE1psfT8F4XwFlYBjvw6xmM086Vckm0Mmh+fEPuoLspl+EgtQzD0F8Ka4qLFGWICvUg==",
"expires_in": 3600,
"refresh_token": "KSamN1Tp4sd26pZJSGK6JobrWOUWorIZ2Y5XxcAqX86K9qoZRp4d3lUH32F4fiT3",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkZyZjdqRC1hc0dpRnFBREdUbVRKZkVxMTZZdyJ9.eyJzdWIiOiJ0b255LnlhdGVzQHN1cGVyb2ZmaWNlLmNvbSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9hc3NvY2lhdGVpZCI6IjUiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvaWRlbnRpdHlwcm92aWRlciI6InN1cGVyb2ZmaWNlLW9ubGluZSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9lbWFpbCI6InRvbnkueWF0ZXNAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L3VwbiI6InRvbnkueWF0ZXNAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L2N0eCI6IkN1c3QxMjAyMCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9pc19hZG1pbmlzdHJhdG9yIjoiRmFsc2UiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvc2VyaWFsIjoiMTUwMTE3ODU4NCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9uZXRzZXJ2ZXJfdXJsIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tL0N1c3QxMjAyMC9SZW1vdGUvU2VydmljZXM4Mi8iLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvd2ViYXBpX3VybCI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbS9DdXN0MTIwMjAvYXBpLyIsImlhdCI6IjE1MTYyOTk2NTYiLCJub25jZSI6IjczNjJDQUVBLTlDQTUtNEI0My05QkEzLTM0RDdDMzAzRUJBNyIsImlzcyI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbSIsImF1ZCI6ImRiMTgzNDAzN2M1OGMwMmI2YmQ5ODk4ZmVlZjE5ODQ1IiwiZXhwIjoxNTE2Mjk5OTU2LCJuYmYiOjE1MTYyOTk1OTZ9.jVW0KWtOeaYV4V3372rSVosPQqlOsaOj6-Oew_Ompe9GZ932aQi6tcc7uXdaz9jmBgLh8mlIZWyW4rFcTnyLQzjjK3nSYWNxxvobQRntigD1lNFYFR7ev9nrYnLw7oTQ9DkuluduWDMcdHYfmImeVNDC93txA_njdmta45ZG0VBeG9lrxInXMdxWXqb_W-ogEaHYbkfugMXwlim7V1c38Wl8QR9QVNImFACzmdma_HBILmUDK9f4XdTA93TnB-WYhesJ_tvdmzrScMIFKANvNNT3smxec6ST-j1uCUBCQrVNxILapXiUrJER4aMmAbFweWs9bbgfhR9_sQVQDmLbVw"
}
Parameter Description
access_token The access token issued by the authorization server.
token_type Provides the client with the information required to successfully utilize the access token to make a protected resource request.
expires_in The lifetime in seconds of the access token.
refresh_token The refresh token which can be used to obtain new access tokens. The refresh token is a long lived token that can be re-used. It is coupled to an end-users consent and is valid as long as the application authorization record (consent) exists. Tenants can revoke authorizations.
  JSON Web Token or JWT, which consists of a Header, Payload and Signature. The claims in the token form part of the payload.

Authorization Code sequence diagram

Authorization Code Flow

 

Refresh Token

A users refresh_token is valid for the lifetime of the application, or until it has been revoked. A refresh_token is used in a POST request as follows:

POST Request (can be tested in a client such as Postman or Fiddler)
https://{env}.superoffice.com/login/common/oauth/tokens? grant_type=refresh_token& client_id=4ref5376616343b38d14ddcd804f2654& client_secret=18f45229e442772a78df5f554e24a456& refresh_token=nKHwerkjh34Yd6QShsnGKk4cFhTwCv3XtJu9PW2X63MtUMygLdI57BJjwCU0& redirect_url=http://localhost/callback

 

Parameter Description
grant_type Required. Must be set to refresh_token
client_id Required. The Application Id assigned to your app when you registered it with SuperOffice.
client_secret Optional for PKCE only, otherwise required.The Application Secret assigned to your app when you registered it with SuperOffice.
refresh_token Required. The refresh token issued as one of the reponse items in the Authorization Code Flow.
redirect_uri Optional. The redirect_uri of your app, where authentication responses are sent and received by your app. It must exactly match one of the redirect_uris registered with SuperOffice.
scope Optional. SuperOffice only supports the scope 'openid', and is implicit for each flow.

 

The response contains the token type, access token, expiration in seconds and identity token.


{
"token_type": "Bearer",
"access_token": "8A:Cust12345.AZuHwfgrRZPHqdjhQyay34ggAgAA8z5BnSYUSk4U4sdfr1Bjzycu0S1NC+xvghQ4VoUz9r6xpF2YAOCj0rb3LWnjLqllp3fYk8h2sxwc8d+5nb5bzGvHLHJ1UIRk38Ye4dPpmLSr4B8UaYNc9gs4Wgfgxqtii+o5w5XTYhPFW1rTcqbXbsnAtv8S+tJWHGPDxi2T/XUHpZxaDp2FT50nVePNiT9tAfP9QQwH0hbXN6RZzKfOcX37DtGcigMLsoc1qM+bJ8oWJqhVbPQIQ4J7DFj5Nr76ecH7rVwpBqxNsOYrek+iLo+KNUovSljIzOXp16y62E5hhs0e+ePThKSS7h52iaq5cwQMj0u2EAInK80UUjRTTpwznJWSlCFXsOD+cSNC6livOOz54PJoejKS+VxRqsr3TYQK+IZbfdxV2MHAtVATpeJOva/aa3XZXiNwSZHPYIZr7fvFnvuTvGJTRSvOR2TuZhy2wl6/qOTLSpG9gvtPD2zjC+BiVmMW/P4Qhv3DWoSFCVqyQISqtFXy3rGexPIL+dz7kutoSkDYhcAl6aO8B0kdYKSsPow+8Jo8N3SD453r9uTGGiAl1tVWXfHo53ehuLJzjtFey4OEn0hJ1YqCybSS9hF2sb5+v2HF36RPpt6bqOuCEIMAcpYJkiQ87kLTqsEGA9AA43sf1RfcB7lbVaVLFGmjUj1jgtIzVKiAR9eyMiWXL3dWMg+WM2Y0MOTsUrSb10kXkJ4g3M4TvH3rV4HTK3ohToxUleYvFbarx/8jeO7oLJfn3nth8NGtd1lJ",
"expires_in": 3600,
"id_token": "eyJ0eFor_Demonstration_PurposeszI1NiIsIng1dCI6IkZyZjdqRC1hc0dpRnFBREdUbVRKZkVxMTZZdyJ9.For_Demonstration_PurposesbSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9hc3NvY2lhdGVpZCI6IjUiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvaWRlbnRpdHlwcm92aWRlciI6ImNlbnRyYWwtc3VwZXJpZCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9lbWFpbCI6InRvbnlAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L3VwbiI6InRvbnlAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L2N0eCI6IkN1c3QyNjc1OSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9pc19hZG1pbmlzdHJhdG9yIjoiRmFsc2UiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvc2VyaWFsIjoiMTgwMTU1MDE5MyIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9uZXRzZXJ2ZXJfdXJsIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tL0N1c3QyNjc1OS9SZW1vdGUvU2VydmljZXM4Ni8iLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvd2ViYXBpX3VybCI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbS9DdXN0MjY3NTkvYXBpLyIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9zeXN0ZW1fdG9rZW4iOiJTdXBlck9mZmljZSBEZXZOZXQgTm9kZSBPSURDLThrOFE3RG1CZ28iLCJpYXQiOiIxNTQ2NjEzMTk4IiwiaXNzIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tIiwiYXVkIjoiNmNmMjUzNzY2MTYzNDNiMzhkMTRkZGNkODA0ZjI4OTEiLCJleHAiOjE1NDY2MTM0OTgsIm5iZiI6MTU0NjYxMzEzOH0.ZzeDsNHJr86pLyqvpPQ5rMzRGd88Fh_RHLdBuG8fBmk_iZnFI5zaARDsTQffEzM30l61rZVmmpQo7KfAN6w27QB6XawURYwye59Z5c3fWRg8BJ4K5Uwik3PxtXtl4A4NWFgZPYyw6t6ZR7kdFng4CQBG0D8I1jF2YZrI8ZO33PtRPisYHJ1F2F5O-qStzCXqhSjd1u7FjsJhqr1xGLDqLzkOm9_0v0nWFHESjBuPhFPIdt6lmcCuy48HGg5G0eM1_3h6SESsukXe0hNMqp3ZHjm5dCEoxE4HziLWSdRZIUa6tkP6wfHDHU_XUJu7PHo8Wx5aG9IBPZ_r1Xd8mgmt6g"
}

 


Implicit Flow

In the Implicit flow, there’re two possible scenarios:

  1. the client application requests just an ID token.
  2. the client application requests both an ID and access token.

Let’s first look at the ID token-only scenario.

After clicking login, the client application redirects the user agent to the authorization endpoint of the Identity Provider. Here in the redirect, Response Type is set to ID Token, indicating the implicit flow and that we’re requesting an ID Token only. Additionally, a nonce value is set to mitigate replay attacks.

GET Request (test in a browser to handle login/redirect)

https://sod.superoffice.com/login/common/oauth/authorize? response_type=id_token& client_id=db1834037c58c02b6bd9898feef19845& redirect_uri=http://localhost/openid/index.html& scope=openid& state=12345& nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7
Parameter Description
response_type Required. Value is id_token token or id_token.
client_id Required. The Application Id assigned to your app when you registered it with SuperOffice.
redirect_uri Required. The redirect_uri of your app, where authentication responses are sent and received by your app. It must exactly match one of the redirect_uris registered with SuperOffice.
nonce Required. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. Client must verify value.
scope Required. Must be openid.
state Recommended. A value included in the request that is also returned in the token response.

As before, the user logs in, and consent to access their identity is requested. When the user gives consent, an Authorization Response message is sent from the Authorization Endpoint, which redirects the user agent back to the client.

The redirection URI includes the ID Token in a URI fragment. A fragment means that, instead of the query string delimited (?) a hash (#) separates the host address and id_token. This ID token contains the standard claims, including some claims normally found in the profile and email scopes.

Response:

http://localhost/openid/index.html# id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkZyZjdqRC1hc0dpRnFBREdUbVRKZkVxMTZZdyJ9.eyJzdWIiOiJ0b255LnlhdGVzQHN1cGVyb2ZmaWNlLmNvbSIsImh0dHA6Ly9zY2hlbWVz LnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9hc3NvY2lhdGVpZCI6IjUiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvZmlyc3RuYW1lIjoiVG9ueSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9sYXN0bmFtZSI6IllhdGVzIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L2lkZW50aXR5cHJvdmlkZXIiOiJzdXBlcm9mZmljZS1vbmxpbmUiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvZW1haWwiOiJ0b255LnlhdGVzQHN1cGVyb2ZmaWNlLmNvbSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS91cG4iOiJ0b255LnlhdGVzQHN1cGVyb2ZmaWNlLmNvbSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9jdHgiOiJDdXN0MTIwMjAiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvaXNfYWRtaW5pc3RyYXRvciI6IlRydWUiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvc2VyaWFsIjoiMTUwMTE3ODU4NCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9yZW1lbWJlcl9tZV9leHBpcmVzIjoiIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L25ldHNlcnZlcl91cmwiOiJodHRwczovL3NvZC5zdXBlcm9mZmljZS5jb20vQ3VzdDEyMDIwL1JlbW90ZS9TZXJ2aWNlczgyLyIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS93ZWJhcGlfdXJsIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tL0N1c3QxMjAyMC9hcGkvIiwiaWF0IjoiMTUxNjE5Mjk0NSIsImF0X2hhc2giOiJIcEtPejlhaUpKN3d6XzVkRE04QU5nIiwibm9uY2UiOiI3MzYyQ0FFQS05Q0E1LTRCNDMtOUJBMy0zNEQ3QzMwM0VCQTciLCJpc3MiOiJodHRwczovL3NvZC5zdXBlcm9mZmljZS5jb20iLCJhdWQiOiJkYjE4MzQwMzdjNThjMDJiNmJkOTg5OGZlZWYxOTg0NSIsImV4cCI6MTUxNjE5MzI0NSwibmJmIjoxNTE2MTkyODg1fQ.DGHBggHTJ2mhsPePeHA5KFP0DLIhadBa64ZGHo7xYYdyS3rTfaUvlaGNdpaS4A1m3lBX6wafvSI8ib9IyrSURLQ7wMLzgfW8W1n3P4tiHB0XfPQc9Nf1nNhA7fz93_jZgnrmOb1rCZDuuBd4E_fAPC_k1Rd9Z0iWBV_Sylx48qdK8D7_FE3buKdfo4ZeeBeRxsEIAHADssNIE4d_lirs-UvCJRBKkN3ZZg4CqnEdUutbZ73c_qCU3T-RhAQhK6sqeki0ywgK_8OS1TUsRQd4oz5aT_9DDcstYnVGHBZOSiwB-yKV9-zJ0SSqQSs1fe-PsEyaomSKMLieRWzoTDnnKQ

The User Agent needs to parse the ID token encoded values that were returned in the URI fragment, and then pass them to the client’s processing logic. The application will likely contain a script that extracts the ID token from the full redirect URI. It’s then up to the client application to validate the ID token prior to accessing and trusting the claims it contains.

In the ID token and access token scenario, the flow is almost the same, except, in the initial redirect we use response type equals id_token token.

GET Request (test in a browser to handle the login/redirect)

https://sod.superoffice.com/login/common/oauth/authorize? response_type=token id_token& client_id=db1834037c58c02b6bd9898feef19845& redirect_uri=http://localhost/openid/index.html& scope=openid& state=12345& nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7

After user authentication and consent is given, instead of just an ID token, the Identity Provider also sends an access token in a URI fragment.

Response:

http://localhost/openid/index.html# access_token=8A%3aCust12020.AUiamiHxsOxM%2bdLC47fudkTQAQAAGbFJt8NXapaIa%2f354f2e2de2bxj8EkRCacoaJ%2fCBeUhiL1FFxw0XFZCl4AZDP3HWSSEIhDWQwxDzlDRzgecSGC4dEZXk8VsmsgqDVoG4cUQFQwxQWlx1FwfwbftxM%2f7ztl%2bIxEfU1UmqsGR5M9Zh8L65mN%2bY5w4T08YJB%2f2kYjVJPIA%2bVPLgLOKX3ck8KkmgCCmTCP%2fpMULOWWnAXxFrrwIAPGKnV6B9wda8DtDprIgtFksw%2fsoZLL%2bhbd2IcJQ1Y9T4xHMROyfFN0%2bV%2ftg1h3%2bYIkWaxRYRjfX0Ybu31qws1Jwo9CcaVeY7aEHzaW2QZieUeETy%2bACxLeScVBOqzbVIcCt0xRdoEfAySllQn2Ty0yam9bVIlv6B6VX9ugLLfG24hxSMWrU05vN3v%2bnbsPr5OnQXNNffYbkI8aeqooF1aGMZlaySo8WXLxWUfUWEgEzTBaWVgLlbIZhE9YeggttfMvdASEYHl808s6SiGUAH5DTPdjjIKXrWWMuXJSA1XkVV3EpS%2f5%2bdZhPq4ENVUmGzMifUDYpd6F74%2fcgrbE6%2fXjuv8K6j3pY9NcO1L6kdoK7StApzVJcYNtT6nu4364EQm2ievwxh1sQOKjcVUK%2bbpcqAIA73uT%2b4%2bfXBUcqJvsq%2fl2oMcKnWjpVf%2f9JmBA%3d%3d& token_type=bearer& state=12345 &expires_in=3600& id_token=eyJ0eXAiO...1QiLCJ...iJSUzI1N...ng1dC...DnnKQ
Parameter Description
access_token The access token issued by the authorization server.
token_type Provides the client with the information required to successfully utilize the access token to make a protected resource request.
state String value used to associate a Client session with an ID Token, and to mitigate replay attacks.
expires_in The lifetime in seconds of the access token.
id_token JSON Web Token or JWT, which consists of a Header, Payload and Signature. The claims in the token form part of the payload.

The client application can validate the ID token, and use the access token and token type to access the tenants web services.

Hybrid Flow

The Hybrid flow is a combination of the Authorization Code and Implicit flows. Tokens can be returned by both authorization and token endpoints.

Where the tokens are returned from depends on the Response Type specified in the redirect URI. The Response Type can be set to either: code token, code id_token, or code id_token token.

If, for example, the client application chooses code id_token, the user agent redirects to the identity provider passing the Response Type equals code id_token along with the openid scope it requires. The end user logs in and is asked for consent.

After consent is given, an Authorization message is sent, which redirects the user agent back to the client application.

The redirection URI includes the authorization code, and ID token.

The ID token is validated the same way as described in the Implicit flow. Then the authorization code is available to send to the token endpoint the same way as described in Authorization code flow. Finally, once the access token is validated, it is sent back, along with another ID token. This ID token can be compared to the previous one for validation.

Hosting Applications in Superoffice

There are cases where, in the SuperID user repository,  a single individual has one user account associated with multiple online installations.

Under those circumstances, after successfully authenticated, the user is presented with a selection of installations to navigate to. 

Under some circumstances this is the prefered behavior, however, in the case where an application is hosted in a SuperOffice Web Panel; and therefore inside a known tenant, having a true single sign-on (SSO) experience is the preferred flow. 

SOD-MultipleTenants.PNG

In there case where the application is hosted inside a SuperOffice web panel and the user should have a true SSO experience, change the applications OAuth 2.0 endpoints to include the tenants customer identifier to bypass the tenant selection screen.

That means instead of using the following generic endpoint:

https://sod.superoffice.com/login/common/oauth/authorize

In the web panel's URL, use the <uctx> template variable to get the customers context identifier and include that in the endpoint.

https://sod.superoffice.com/login/{contextIdentifier}/oauth/authorize

// example

https://sod.superoffice.com/login/Cust12345/oauth/authorize

This will ensure the web panel application provides the user with seamless SSO experience.

Conclusion

In this article, we reviewed the basic concepts of Open ID Connect. This included defining participants, identity tokens, claims and scopes, and endpoints. We looked at the different flows developers can choose from when enabling client applications to use OpenID Connect.

We looked at how OpenID Connect allows client applications to verify an End Users identity, and obtain basic profile information about that user using REST API’s.

We also saw how OpenID Connect provides client applications with the when, where and how the authentication occurred, and how it can be used to allow federated single sign on.

Finally we demonstrated how applications hosted in web panels should use then endpoints to provide a seemless SSO experience for users.

Legg ut kommentar Til toppen