A quick-start guide for implementing Single Sign-On / Authentication using OAuth 2.0 for a Web Server Application with Authorization Code Grant flow

Introduction

The 10Duke Identity Provider (IdP) API offers a quick and simple means of providing users access to cloud and corporate applications using a single identity. You can connect any application to the 10Duke IdP and each time a user tries to authenticate, the 10Duke IdP will verify their identity and send back to your application the information it requires.

This tutorial covers implementing authentication in your application with the 10Duke Identity Provider by using the OAuth 2.0 with OpenID Connect identity protocol.

Terminology / Roles

  • The Authorization Server
    This is the IdP server that grants access tokens and identity tokens for users that it has authenticated.

  • The User Agent
    This is the browser and e.g. desktop applications and mobile applications.

  • The Third-Party Application: "Client"
    The application that needs to authenticate the user and access APIs of the Identity Provider on behalf of the user.

  • The User: "Resource Owner"
    The person who is authenticated by the Identity Provider. When using OAuth 2.0, client application can also access resources owned by the authenticated user via APIs of the Identity Provider.

  • OpenID Connect
    OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the Resource Owner based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the Resource Owner in an interoperable and REST-like manner.

API / Service endpoints

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

Step 1. Register your application with the 10Duke IdP

We will need to collect some basic information about your application to create a new client and issue the client_id and client_secret credentials.

Please send the below details to info@10Duke.com and we will respond by email.

  • your app name eg. “myapp”
  • Login callback url (redirect_uri > this is the url used to redirect the user agent after a successful authentication)
  • (Optional) Logout callback URL (this is the url used to redirect the user agent after a successful logout)

Step 2. Get your application keys

Once you have provided us with your app name and login callback url, we will provide you with the client ID and client secret. Your application will need this information about the client to communicate with the IdP.

  • Client_id = YOUR_CLIENT_ID
  • Client_secret = YOUR_CLIENT_SECRET
  • 10Duke IdP deployment: https://test-idp.10duke.com/your_app

Step 3. Choose your OAuth 2.0 SSO Variant

When implementing SSO generally, there are several approaches you can take. These variants depend on the types of application you are connecting to the SSO system (mobile, web, or desktop) and if you’re working with OAuth 2 or SAML 2. To learn more, please see the IdP Developer Guide and the “Single Sign-On Variants” section of it.

For this tutorial, we’ll use the Authorization Code Grant flow. This example applies in the case in the case of a web server application that interacts with the user via a browser.

Step 4. Execute Authorization Code Grant

  1. When the client web application needs to authenticate the user, it will need to send the user to the IdP that handles user authentication on behalf of the client application.

    • You need to assemble the URL used to redirect the user agent to the 10Duke IdP for the purpose of authenticating the user and getting an access token. An example url looks like:

      [IDP_BASE_URL]/oauth2/authz/?response_type=code&client_id=[YOUR_CLIENT_ID]&redirect_uri=[CLIENT_CALLBACK_URL]&scope=openid+profile
    • You will then need to redirect to the authorization endpoint of the 10Duke IdP. Please note that your application will instruct the browser to navigate to the 10Duke IdP using a redirect.

  2. Once the the 10Duke IdP has authenticated the user, it will send the user agent back to the client, to the URL set in redirect_uri, with an authorization code.

  3. Now you will need to exchange the received authorization code for an access token. The endpoint in your application’s back-end (the redirect_uri) should assemble a further OAuth 2.0 request (POST) to fetch the access token by presenting the received authorization code.

    • The information required for this call is:
      • URL to POST to is the access token endpoint: /oauth2/access/ at the IdP
      • Parameters:
        • grant_type=authorization_code
        • code=the value from code parameter from step 2
        • client_id=’YOUR_CLIENT_ID’
        • client_secret=’YOUR_CLIENT_SECRET’
        • redirect_uri=same url used in step 1

Steps 4.1 & 4.2 involve the browser and calls to the 10Duke IdP are from the user agent. Step 4.3 involves the client’s back-end only, the HTTP call is a server to server call using HTTP POST.

Once you’ve completed the request in Step 4.3, there will be an OAuth / OpenID Connect access token response. This response is given as a JSON object, and it is successful if the JSON object contains access_token and id_token fields.

id_token can then be used for reading information of the authenticated user. access_token can be used for making OAuth calls to APIs of the IdP.

The access token response is described here: http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse

Please see https://github.com/10Duke/10duke-dotnet-client for two practical ASP.NET client application examples.

Step 5. Confirming delegation of authentication to the 10Duke IdP

Congratulations, if you have integrated your test application to the IdP correctly you should now be able to sign-in to your test application and see it delegate authentication to the IdP (watch your browser urls change as it does this) and then return you, as a logged-in user, back to your test application.

If you run into any issues, please raise them on StackOverflow, tag them “10Duke”, and we’ll respond asap.