Skip to content

Authenticate a user for API access using GitHub OAuth

Jump to bottom
David Garvey edited this page Sep 12, 2018 · 15 revisions

This example shows how to use the Tyk Gateway and Identity Broker to allow users to access an API using their GitHub credentials. This uses an OAuth 2.0 flow, so you could swap out GitHub for other OAuth 2.0 providers.

Prerequisites

For this example we are using:

  • Gateway 1.6.1
  • Dashboard 2.6.1
  • Identity Broker 0.3

Application configuration

The application configuration should be set up as standard. See configuring Tyk Identity Broker.

Brief overview

This assumes you have a good understanding of the Tyk products already and just need guidance on the configuration.

Identity Broker profile

{
    "ActionType": "GenerateOAuthTokenForClient",
    "ID": "1",
    "IdentityHandlerConfig": {
        "DashboardCredential": "<DASHBOARD_USER_API_KEY>",
        "DisableOneTokenPerAPI": false,
        "OAuth": {
            "APIListenPath": "<API_LISTEN_PATH>",
            "BaseAPIID": "<API_ID>",
            "ClientId": "<OAUTH_CLIENT_ID>",
            "RedirectURI": "<OAUTH_CLIENT_REDIRECT_URI>",
            "ResponseType": "token",
            "Secret": "<OAUTH_CLIENT_SECRET>",
            "NoRedirect": false
        }
    },
    "MatchedPolicyID": "<POLICY_ID>",
    "OrgID": "<ORGANISATION_ID>",
    "ProviderConfig": {
        "CallbackBaseURL": "<IDENTITY_BROKER_HOST>",
        "FailureRedirect": "<DASHBOARD_HOST>",
        "UseProviders": [{
            "Key": "<GITHUB_APPLICATION_CLIENT_ID>",
            "Name": "github",
            "Secret": "<GITHUB_APPLICATOIN_CLIENT_SECRET>"
        }]
    },
    "ProviderName": "SocialProvider",
    "ReturnURL": "",
    "Type": "redirect"
}
  • ID: Profile Id which will be used when accessing the Identity Broker endpoint. Must be unique in profiles.json.
  • IdentityHandlerConfig.DashboardCredential: Tyk Dashboard API Access Credentials of the Dashboard user. Must be in the same Organisation as the API referenced by IdentityHandlerConfig.OAuth.BaseAPIID.
  • IdentityHandlerConfig.OAuth.APIListenPath: Listen path of the OAuth API.
  • IdentityHandlerConfig.OAuth.BaseAPIID: Id of the OAuth API.
  • IdentityHandlerConfig.OAuth.ClientId: Client Id of the OAuth client for the OAuth API.
  • IdentityHandlerConfig.OAuth.RedirectURI: Redirect URI of the OAuth client for the OAuth API. This should be the URL of the web application which wants to use Identity Broker. It will receive the API token at this URL.
  • IdentityHandlerConfig.OAuth.Secret: Secret of the OAuth client for the OAuth API.
  • MatchedPolicyID: Policy Id of the policy which grants access to the OAuth API.
  • OrgID: Organisation Id of the user referenced by IdentityHandlerConfig.DashboardCredential.
  • ProviderConfig.CallbackBaseURL: Publicly accessible URL of the Identity Broker. Remember to include the port number e.g. http://my-identity-broker:3010.
  • ProviderConfig.FailureRedirect: Publicly accessible URL of the Dashboard.
  • ProviderConfig.UseProviders.Key: Client ID of the GitHub OAuth application.
  • ProviderConfig.UseProviders.Secret: Client Secret of the GitHub OAuth application.

Note that you will have to create the GitHub OAuth application before you can fully complete the Identity Broker profile.

GitHub OAuth application

Create an OAuth application in GitHub.

  • Set Authorization callback URL to the publicly accessible Identity Broker callback URL. This will have the same hostname as the profile ProviderConfig.CallbackBaseURL but will also include the callback path which includes the profile ID and ProviderConfig.UseProviders.Name e.g. http://my-identity-broker:3010/auth/1/github/callback.

The Client Id and Client Secret are needed in the Identity Broker profile.

  • Set ProviderConfig.UseProviders.Key to the Client Id.
  • Set ProviderConfig.UseProviders.Secret to the Client Secret.

Test the solution

Note: Make sure you have restarted the Identity Broker before testing the solution. This will allow it to reload the profile configuration.

When your web application wants to authenticate a user against the API, it should redirect the user to:

<IDENTITY_BROKER_HOST>/auth/<PROFILE_ID>/<PROVIDER_NAME> e.g. http://my-identity-broker:3010/auth/1/github.

  • http://my-identity-broker:3010: Publicly accessible URL for the Identity Broker, as defined in the profile ProviderConfig.CallbackBaseURL.
  • auth: Endpoint for Identity Broker authentication API calls.
  • 1: ID of the Identity Broker profile.
  • github: ProviderConfig.UseProviders.Name of the Identity Broker profile.

Redirecting the browser to this URL will trigger Identity Broker to redirect to GitHub where the user is presented with the GitHub OAuth application sign in page. When the user successfully authenticates with GitHub they are redirected to the URL defined by the profile IdentityHandlerConfig.OAuth.RedirectURI, which the Identity Broker will append with the token data:

http://my-web-application/#access_token=5b8e119821702e000196c3dbe53e1f88fdd24619b4558e13087e3bd1&expires_in=3600&token_type=bearer

  • access_token: Token which can be used to access the API.
  • expires_in: Time which the token is valid for, from the time of issue.
  • token_type: Type of token.

Tyk will also store metadata accumulated during the OAuth flow. This is accessible by inspecting the token directly via the Tyk APIs.

Full Process (TBC...)

Create an OAuth 2.0 API in the Dashboard

Click APIs, then Add new API.

  • Set API Name to OAuth API
  • Set Listen Path to /oauth-api/
  • Set Authentication Mode OAuth 2.0
  • Set Allowed Access Types to Client Credentials
  • Set Allowed Authorize Types to Token

Click Save.

Go back into your API definition and note the API Id, we will need this later.

Create a policy for the API

Click Policies, then Add Policy.

  • Set Policy Name to OAuth API Policy
  • Set Access Rights to OAuth API

Click Create.

Note the Policy Id for the OAuth API Policy, we will need this later.

Set up an OAuth client for the API

Click APIs, then Actions dropdown for the OAuth API and select OAuth Clients, then Add New Client.

  • Set Redirect URI to the URL for your application e.g. http://my-web-app.com
  • Set Available Policies to OAuth API Policy

Click Add new client.

Click View for the OAuth Client you just created.

Note the Client Id and Client Secret, we will need them later.

Note your Dashboard credentials and Organisation Id.

Click Users, then Actions dropdown for the your user and select Edit.

Note the Tyk Dashboard API Access Credentials and Organisation Id, we will need them later.

Set up GitHub OAuth application

Log into GitHub.

Go to your profile Developer Settings.

Click New OAuth App.

  • Set Authorization callback URL to the URL from which your identity broker callback URL e.g. http://ddbef94f.ngrok.io/auth/1/github/callback.

Set up Identity Broker profile

Clone this wiki locally