Skip to content

Authenticate a user for API access using GitHub OAuth

Jump to bottom
David Garvey edited this page Feb 15, 2019 · 15 revisions

This example shows how to use the Tyk API 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.

Watch the accompanying using Tyk Identitiy Broker and OAuth 2.0 with GitHub to generate API tokens video.

Prerequisites

For this example we are using:

  • Gateway 2.6.1
  • Dashboard 1.6.1
  • Identity Broker 0.3

Application configuration

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

Solution

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

Identity Broker profile

The Identity Provider's profile.json file configures how it will process authentication requests. Add this profile to it:

{
    "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_APPLICATION_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: You will have to create the GitHub OAuth application before you can fully complete the Identity Broker profile. You will also need to have created an API, Policy and OAuth Client in the Dashboard.

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: Once you have saved your Identity Broker profile, make sure to restart the Identity Broker before testing the solution. This will allow the new profile configuration to be loaded.

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.

Clone this wiki locally