Implementing OAuth SP-based SSO

This tutorial explains how to implement SSO with external OAuth service providers. As an example setup, you will be implementing your login with the following conditions:

  • Login will use GitHub OAuth authentication.
  • Users will sign up for a member account on Kuroco if they do not already have one.
  • New members will belong to the "guest" user group.

Due to changes in the GitHub specifications, the client ID and client secret acquisition methods may differ from this tutorial. For details, please check the latest information on the GitHub website.

Setting up your OAuth SP

1. Add an extended item in the member module for ID storage

To create an extended item for storing the GitHub token, go to [Member] -> [Member] in Kuroco's sidebar menu.

Image from Gyazo

On the member list screen, click the [Member] link above the page title and select [Advanced member settings] in the dropdown menu.

Image from Gyazo

On the advanced member settings screen, click [Configure extended item settings for members].

Image (fetched from Gyazo)

Create a new entry with the settings below and click [Update] to save it.

ItemSetting
DisplayGitHub token
Datagithub_token
TypeText

2. Configure your OAuth SP in Kuruco's admin panel

In the left sidebar menu, under "SETTINGS", click [External system integration] -> [OAuth SP].

fetched from Gyazo

On the OAuth SP screen, click [Add] to open up the SSO OAuth SP editor screen.

fetched from Gyazo

Enter the following settings in the editor.

ItemSetting
Login OAuth SP nameEnter a recognizable name for the OAuth SP.
Target domainAdmin panel
TypeGitHub
Automatic user registrationEnable this option and select "Guest" from the dropdown list.
Store the ID in Member Ext Col and link without using emailEnable this option and select [GitHub token] from the dropdown list.

Click [Add] at the bottom of the screen to save these settings.

fetched from Gyazo

You will be redirected back to the OAuth SP list. Click the title of the entry you just created, and note down the login URL on the editor screen.

fetched from Gyazo

3. Add OAuth apps on GitHub

Next, we will configure the GitHub settings. Go to GitHub's OAuth applications page and click [Register a new app].

fetched from Gyazo

Enter the following information and click [Register app].

ItemSetting
Application nameName of your app.
Homepage URLYour site URL.
Authorization callback URLYour login URL from Step 2.

fetched from Gyazo

4. Generate a client secret on GitHub

From your OAuth apps page, click [Generate a new client secret].

fetched from Gyazo

Note down your client ID and client secrets. Client secrets will not be displayed again once you navigate away from this page.

fetched from Gyazo

5. Update your OAuth SP settings on Kuroco

Return to your Kuroco admin panel. Click [External system integration] -> [OAuth SP] in the sidebar menu.

fetched from Gyazo

Click the name of the OAuth SP that you added in Step 2.

fetched from Gyazo

Enter the client ID and secret that you noted down in Step 4.

fetched from Gyazo

Signing in via OAuth SP

After you've set up your target domain and SP settings in the admin panel, the "Login with your external account" option for your SP of choice will appear on your login screen.

fetched from Gyazo

Also, clicking the login URL in the SSO OAuth SP edit screen will redirect you to the GitHub login screen by default. Alternatively, you can use this URL to create your own login page.

fetched from Gyazo

More information

Retrieving your client ID and private key

The table below shows you where to get the client IDs and secret keys for the main identity providers available in Kuroco. Refer to this when you implement SSO with aother IdPs.

IdPURLVariable names
GitHubhttps://github.com/settings/developersClient ID, client secret
Googlehttps://console.cloud.google.com/apis/credentialsClient ID, client secret
Facebookhttps://developers.facebook.com/appsApp ID, app secret

Customization

You can implement OAuth SP-based SSO for services that are not listed in the type options by setting up a custom type. First, make sure the identity provider you are trying to connect to supports OAuth 2.0. Then, refer to the documentation of the IdP and configure the authentication in the SSO OAuth SP module.

To test if your settings are correct, click [Test] at the bottom of the SSO OAuth SP edit screen. This will verify the response from the identity provider and configure the parameters accordingly.

fetched from Gyazo

You must save your settings before running the test. Unsaved cannot be tested.

If you have any other questions, please use our contact form or Slack workspace.