The 10Duke Identity Provider Developer Guide

identity_developer-guide.pdf

Introduction

This document serves as a source for technical integration information when using the 10Duke Identity Provider.

The 10Duke Identity Provider (IdP) offers the means by which end users are able to simply and securing access one or more applications web, mobile or desktop applications using a single identity. It supports:

  • Single Sign-On (SSO), in which a user can use the same credentials (typically username and password) to sign in once to a single application and then also, in the same session, be also be able to access other online applications, without the need to sign-in again.

  • Federated Identity Management (FIM) in which two or more Identity Providers communicate together in order to authenticate and end user based on their “home” directory. Federation normally involves connecting two or more corporate Identity Providers, with each responsible for authenticating any user it holds, and the consequent authentication decision trusted and relied upon by any connecting Identity Provider or client application.

  • Multi-Factor Authentication (MFA) in cases where a username and password alone are deemed an insufficient means of authenticating an end user. A mobile One-Time Password (OTP), card reader, fingerprint scanner or finger-vein reader are all additional authentication factors that can be added into the authentication chain of the 10Duke Identity Provider if required.

Provided on a white-label basis, this Single Sign On (SSO) capability provided by the 10Duke Identity Provider can be extended to a variety of actors include public customers, employees within a company, business partners, or applications and middleware components, enabling SSO for consumers as well as between organizations.

The IdP supports the use of OAuth 1.0a, OAuth 2.0 with OpenID Connect and SAML 2.0. Further information and descriptions of each protocol are provided in the Further Reading section of this guide.

Prerequisites

Developers are assumed to have knowledge and experience with the following:

  • HTTP
  • Basics of security protocols, e.g. OAuth, SAML, etc. (required if developing service providers, not required if only using the IdP directly)
  • Concepts of modelling and using business entities and relations
  • XML
  • JSON
  • Json Web Tokens
  • Base64 encoding

How SSO Works

In an SSO system there are three main entities to be aware of. The first is the Identity Provider that sits at the heart of the system and enables SSO. The second entity is the client application (or applications) that you want the end user to be able to sign-in to. (In SAML terms, the client application is called the “Service Provider” or “relying party”. In OAuth terms, it is referred to as a “consumer application”.) The third entity is, of course, the end user.

In creating the SSO system, each client application needs to delegate authentication to the 10Duke IdP. The IdP has only one responsibility and that is to authenticate end users. With the IdP taking care of authentication, this means that each client application can just focus on whatever its does (email, blog site, aerodynamics simulation, etc) .

Each client application normally communicate with the IdP using one of two protocols - OAuth 2+OpenID Connect or SAML 2. Check out the Further Reading section for more detail, but very broadly, SAML is used for Enterprise SSO scenarios while OAuth tends to be preferred for Internet-based applications.

Client Libraries

If the application(s) you are connecting to the IdP do not yet support either SAML 2 or OAuth2+OpenID Connect, you can use the 10Duke client libraries to help. They provide a simple and flexible way to access the APIs functionality from your preferred language.

Go to Github to see the libraries available and select the one you need. If there isn’t a client library there that you’d like to see, please let us know and we’ll try to add it or we can point you in the direction of a suitable open-source library to use.

Single Sign-on Variants

When implementing SSO, there are several approaches you can take. These variants depend on the type of application you are connecting to the SSO system (mobile, web, or desktop) and if you’re working with OAuth 2 or SAML 2.

If your application supports SAML 2, then the integration process is straightforward and there is one implementation option. If your application supports OAuth 2, then there are three variants to choose from;

  1. Authorisation code grant: used in cases when a web server interacts with the user via a browser. Can also be used with mobile and desktop applications.

  2. Implicit grant: used in cases when a browser interacts with the user and IdP directly without its own server side involved at all. Can also be used with mobile and desktop applications.

  3. Resource Owner Password Grant: used in cases where a “direct API call” login requirement is made by the client application. When using this option, the password of the user is supplied by the client, and SSO features like social login and federation are not available.

Use the table below to select the SSO variant that is most appropriate for the application you are connecting to the IdP. Use the link to take you directly to the relevant section of this developer guide.

QuickStart Tutorial 1
If you’re looking to integrate a simple web application, you may want to take a look at the 10Duke IdP Tutorial 1 which will walk you through the process of getting a simple web-application using Javascript delegating authentication to the 10Duke IdP. You can refer back to this developer guide as needed.

OAuth 2.0

Explanation of terminology

This is a summary of the most central items in the OAuth 2 specification and how they relate to client applications using the 10Duke Identity Provider. The full current OAuth 2.0 Framework specification can be found at https://tools.ietf.org/html/rfc6749

OAuth Term Description / mapping to 10Duke IdP
Authorization Server 10Duke Identity Provider
User agent Browser and e.g. desktop applications and mobile applications
Client or Consumer E.g. server applications, desktop applications and mobile applications (note that desktop and mobile apps may play in different roles)
Resource owner E.g. the user
OpenID Connect Extension that specifies standard way or requesting information about the logged in user. *see endpoints below

API / Service endpoints

Item URL (relative, prepend environment base URL)
Authorization code /oauth2/authz/
Access token /oauth2/access/
User info /userinfo/

OAuth 2.0 SSO Implementation Variants

Authorization code grant

This example applies in the case of a web server that interacts with the user via a browser.

  1. First the client redirects the user agent (browser) to the IdP (authorization server). The call below shows the browsers reaction to the redirect

    GET /oauth2/authz/?response_type=code&client_id=todo_api_key&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcallback HTTP/1.1
     Host: {IDP_HOST}
  2. Next, once the user is successfully authenticated, the IdP (authorization server) redirects the browser back to the client (client web application)

    HTTP/1.1 302 Found
    Location: https://client.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz
  3. The client receives the request from the browser and extracts the code token. The client’s next request to the IdP is to exchange the code for an OAuth access token:

    POST /oauth2/access HTTP/1.1
    Host: {IDP_HOST}
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
  4. An example successful response could be

    HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8
    Cache-Control: no-store
    Pragma: no-cache
    
    {
      "access_token": "ACCESS_TOKEN_VALUE",
      "refresh_token": "REFRESH_TOKEN_VALUE",
      "id_token": "eyJhbGciOiJub25lIn0.e3N1Yjpzb21lLXV1aWQsYXVkOm9hdXRoLWNsaWVudC1pZCxpc3M6SURQX0hPU1QsZXhwOjE0NjcwMzUyMzAsZ2l2ZW5fbmFtZTpGaXJzdE5hbWUsaWF0OjE0NjcwMzQ5MzAsZmFtaWx5X25hbWU6RmFtaWx5TmFtZX0=.",
      "token_type": "Bearer",
      "expires_in": 31536000
    }

QuickStart Tutorial 2
If you’re looking to integrate a web-server application, you may want to take a look at the 10Duke IdP Tutorial 2 - it will walk you through the process of getting your application to delegate authentication to the 10Duke IdP. You can refer back to this developer guide as needed.

Implicit flow

This example applies in the case of a browser / desktop application interacts with the user and IdP directly without its own server side involved at all.

  1. First the browser sends the user agent (browser) to the IdP (authorization server) . “Sends” here can be done using JavaScript code or predefining a link / button that contains the URL to navigate to. The call below shows what clicking a link in the web page looks like:

    GET /oauth2/authz/?response_type=token+id_token&scope=profile+email&client_id=todo_api_key&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&state=xyz&nonce=todo_nonce HTTP/1.1
    Host: {IDP_HOST}
  2. Next, once the user is successfully authenticated, the IdP (authorization server) redirects the browser back to the client (client web application)

    HTTP/1.1 302 Found
    Location: https://client.example.com/cb#access_token=bNXrLNRSR-hWHRa109MUcYagUGM&token_type=Bearer&expires_in=31536000&state=xyz&id_token=e2F0X2hhc2g6IHlLTE1IRlhrNEo3TzBpMS1WejM1Wnc9PSxzdWI6IGRhMjFhOWZiLTU5NmItNGI3MS1hODZmLWM0Y2YyN2RlN2ZlZSxhdWQ6IHRvZG9fYXBpX2tleSxpc3M6IGh0dHBzOi8ve0lEUF9IT1NUfTo0NDMsZXhwOiAxNTE1ODQ4MTcwLGdpdmVuX25hbWU6IFRlc3QsaWF0OiAxNTE1NzYxNzcwLG5vbmNlOiBhZGQxMmQxYy1jNzZiLTQwYzYtODhlZS1iYzQwMDNkNTQ1NGYsZmFtaWx5X25hbWU6IFVzZXJ9
  3. The client will then parse the request URL and extract the access token. The login call back information is contained in URL parameter form in the URL fragment (after the # character in the URL)

  4. Next, the client may use the IdP API, including the /userinfo API, to fetch more information about the logged-in user. Any subsequent call should include the OAuth 2.0 Access Token in the Authorization header. See the section about /userinfo API.

  5. See also this example with a HTML / JQuery implementation of implicit flow: https://github.com/10Duke/oauth-java-webapp-example/blob/master/com.tenduke.example.scribeoauth/src/main/webapp/index.jsp

Resource owner password grant

This example maps to the “direct API call” login requirement given by example client application:

POST /oauth2/access HTTP/1.1
Host: {IDP_HOST}
Content-Type: application/x-www-form-urlencoded


grant_type=password&username=alfred&password=secret&scope=openid profile&client_id=todo_api_key&client_secret=todo_api_secret
Refreshing an access token

This request example applies to Authorization code OAUth 2.0 flow.

POST /access HTTP/1.1
Host: {IDP_HOST}
Content-Type: application/x-www-form-urlencoded


grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&scope=openid%20profile&client_id=todo_api_key&client_secret=todo_client_secret
Userinfo (OpenID Connect)

This request example applies to all OAUth 2.0 flows and serves the purpose of getting logged-in user info after login is successful. (See also the section below about the Graph API and user query for a more versatile alternative.)

GET /userinfo HTTP/1.1
Host: {IDP_HOST}
Authorization: Bearer OeRIO5cbQkvTFRCgostl8V7xZGU

NOTE:

  • Authorization: Bearer OeRIO5cbQkvTFRCgostl8V7xZGU holds the access token value as the authorization token.
  • Information returned by the /userinfo endpoint is controlled by the scope names set by the client when initiating the SSO process. Standard claims that are applicable as scope names are listed here under section 5.1 "Standard claims": http://openid.net/specs/openid-connect-core-1_0.html

OAuth 2.0 and Desktop Applications

When including a desktop application in an SSO system, there are two options to choose from depending on your requirements. The diagram below presents a simplified comparison of the two desktop flows that can be implemented. A more formal flow can be found at: https://tools.ietf.org/html/rfc6749#section-4.2:

Diagram 1 Diagram 1: Resource owner password grant flow

Diagram 2 Diagram 2: Implicit grant flow

Diagram 3 Diagram 3: Authorization code grant flow

Desktop Apps and Resource Owner Password Credentials Grant

In this scenario, Resource Owner Password Credentials Grant remains one single call to the IdP’s access token endpoint. Key things to note:

  • This variant rules out delegation further upstream because the Resource Owner Password Credentials Grant flow does not have the means to relay credentials and tokens over several tiers.

  • Choose this variant as the last alternative if none of the others can be utilized. Scenarios may include supporting legacy components, etc. more rare use cases.

Desktop Apps and Implicit Grant Flow

Using the embedded browser and Implicit Grant, the flow will be:

  1. Desktop app opens embedded browser. The browser URL is set to the OAuth authorization endpoint of the IdP, parameterised for the OAuth Implicit Grant flow.
  2. The IdP displays login page.
  3. Once the login credentials have been confirmed the IdP redirects the browser to the callback URL.
  4. The desktop application handles the callback request and parses the OAuth response from the request URL.

Desktop Apps and Authorization Code Grant Flow

Using the embedded browser and Authorization Code Grant, the flow will be:

  1. Desktop app opens embedded browser. The browser URL is set to the OAuth authorization endpoint of the IdP, parameterised for the OAuth Authorization Code Grant flow.
  2. The IdP displays login page.
  3. Once the login credentials have been confirmed the IdP redirects the browser to the callback URL.
  4. The desktop application handles the callback request and parses the OAuth authorization code from the request URL.
  5. The desktop application makes a direct request to the access token endpoint of the IdP, using the authorization code.
  6. The IdP returns the OAuth access token response.

OAuth 1.0a

OAuth 1.0a is supported by the 10Duke IdP. It can be enabled upon request.

SAML 2.0

The required SAML 2.0 settings / configuration is provided per environment and delivered via the 10Duke Identity Provider’s federation metadata service. If you have a deployed 10Duke IdP, these can be found in SysAdmin>Identity>Single Sign-in. If you do not have access to a deployment IdP environment, please send a support request to support@10duke.com or contact your 10Duke account manager.

The SAML 2.0 metadata specification (federation metadata) can be accessed here:

SAML flow incorporating an existing customer Identity Provider

Diagram 4 Diagram 4: SAML flow with an existing identity provider

SAML flow without a customer’s existing Identity Provider

Diagram 5 Diagram 5: SAML flow without an existing Identity Provider

Single Sign-out

Summary of Single Sign-out service and variants available:

Protocol IdP Logout URL
OAuth 2.0 /logout
OAuth 1.0a /logout
Saml 2.0 /logout

OAuth 2.0

Parameter Value / Description
triggerSingleSignout Flag that control if “upstream” sign-out must be triggered. E.g. bubble Sign-out all the way up to ADFS.
oauthConsumerKey OAuth client Id

OAuth 1.0a

Parameter Value / Description
triggerSingleSignout Flag that control if “upstream” sign-out must be triggered. E.g. bubble Sign-out all the way up to ADFS.
oauthConsumerKey OAuth client Id

SAML 2.0

Parameter Value / Description
triggerSingleSignout Flag that controls if “upstream” sign-out must be triggered. E.g. bubble Sign-out all the way up to ADFS.
Body Value / Description
SAML Logout request message See SAML specification: http://saml.xml.org/saml-specifications and Federation metadata in a specific 10Duke IdP deployment.

Client requirements

URL / Endpoint Value / Description Optional
Logout callback The IdP will notify all clients with a known logout callback URL when the user is signed out.

The callback is a “best effort” FYI type of a call. Clients are expected to respond with HTTP 200 status code. However, failure to respond with HTTP 200 or respond at all will not cripple sign out. Errors will also not be logged or traced at the IdP end.
Yes

Security configuration

Public key for verifying JWT signatures

  • (RSA, X509 Encoded)
  • In JWT lingua: RS256
-----BEGIN PUBLIC KEY-----
...
JWT PUBLIC KEY, CONFIGURED PER ENVIRONMENT
...
-----END PUBLIC KEY-----

SAML message signing Certificate with public key info

This certificate can be used in SAML providers, including Microsoft ADFS to validate SAML message signatures produced by the 10Duke Identity Provider

-----BEGIN CERTIFICATE-----
...
SIGNING CERTIFICATE, CONFIGURED PER ENVIRONMENT
...
-----END CERTIFICATE-----

Interacting with the 10Duke Identity Provider

There are four main ways to interact with the 10Duke IdP:

  1. REST API 2 .Graph API
  2. The User Interface (UI) components of the 10Duke IdP
  3. 10Duke SysAdmin application

REST vs Graph APIs

There are two ways in which you can make calls to the 10Duke IdP; using REST or via a Graph API. Most of the examples given in this guide make use of REST, as it is better known and offers a more standardized approach to interacting with the 10Duke IdP. The Graph API is generally harder to approach initially for many developers, but once you begin to understand its syntax, it tends to offer more flexibility, particularly for more advanced use cases. As a general tip, look to REST first. If it doesn’t give you what you need, try the Graph API.

The 10Duke IdP REST API can be found here.

The 10Duke IdP Graph API can be found here.

REST API

The primary means of interacting with the 10Duke IdP is via its REST API. The following table provides an overview of key endpoints you can call.

More information on REST in general can be found here.

Example Endpoints:

Description Endpoint
Get user info GET /user-info/{userId}
List user info GET /user-info/{userId}
Delete user DELETE /users/{userId}
List organizations a user is a member in GET /users/{userId}/organizations
Assign an organization roles to user POST /users/{userId}/organization-roles
List users organization roles GET /users/{userId}/organization-roles
Add a user to an organization group POST /users/{userId}/organization-groups/{groupId}
List users organization groups GET /users/{userId}/organization-groups
List groups in the organization GET /organizations/{organizationId}/groups

Graph API

The Graph API offers a more advanced manner of interacting with the 10Duke IdP. It is less prescriptive that REST and so for some developers and requirements, is a preferred option. The Graph API is a representation of the information held in a 10Duke Identity Provider deployment. It is an API that models the data in terms of objects and the relationships between them and allows the client to interact with multiple nodes in a single request

To learn more about how the Graph API works, please see the Graph API reference.

The IdP’s UI components

In a basic deployment, there are typically four main pages that the end user interacts with:

  1. The Registration Form
  2. The Sign In Box
  3. The Profile/My Account Page
  4. The Logged Out Page

Customizing the look and feel of the IdP User Interface

The 10Duke IdP utilises bootstrap 3.3.6. To customize the appearance of the IdP, you can use your own logo and apply any* bootstrap theme on top of it.(Some manual tweaking may be necessary depending on theme. The html is currently fixed, and cannot be customized.)

The preferred option:

Send your 10Duke integration team

The alternative option:

Send your 10Duke integration team:

  • a complete bootstrap theme as a css file
  • your logo, preferably as a transparent png
  • all assets, or urls to dynamically loaded assets required by your bootstrap theme (images, fonts etc.)

10Duke SysAdmin

10Duke SysAdmin is a web-based admin tool that allows an administrator of a deployed 10Duke Identity and Entitlement System to manage both identities and entitlements in the system as well as view event based data and summary level charts depicting activity within the system. This guide is intended to assist an admin to understand how basic tasks in the system are carried out.

Please read the 10Duke SysAdmin User Guide for more detail on the capabilities of this application. If you do not have a copy of this guide please let us know: support@10duke.com

References and Further Reading

Some technologies and libraries supporting the standards on different platforms:

OAuth

OpenID Connect

OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol, which allows clients to verify the identity of an end-user based on the authentication performed by the Identity Provider, as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner.

Note that OpenID Connect is different from OpenID which is an authentication protocol for distributed authentication and technically unrelated to OpenID connect

SAML