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.
On the member list screen, click the [Member] link above the page title and select [Advanced member settings] in the dropdown menu.
On the advanced member settings screen, click [Configure extended item settings for members].
Create a new entry with the settings below and click [Update] to save it.
| Item | Setting |
|---|---|
| Display | GitHub token |
| Data | github_token |
| Type | Text |
2. Configure your OAuth SP in Kuruco's admin panel
In the left sidebar menu, under "SETTINGS", click [External system integration] -> [OAuth SP].
On the OAuth SP screen, click [Add] to open up the SSO OAuth SP editor screen.
Enter the following settings in the editor.
| Item | Setting |
|---|---|
| Login OAuth SP name | Enter a recognizable name for the OAuth SP. |
| Target domain | Admin panel |
| Type | GitHub |
| Automatic user registration | Enable this option and select "Guest" from the dropdown list. |
| Store the ID in Member Ext Col and link without using email | Enable this option and select [GitHub token] from the dropdown list. |
Click [Add] at the bottom of the screen to save these settings.
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.
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].
Enter the following information and click [Register app].
| Item | Setting |
|---|---|
| Application name | Name of your app. |
| Homepage URL | Your site URL. |
| Authorization callback URL | Your login URL from Step 2. |
4. Generate a client secret on GitHub
From your OAuth apps page, click [Generate a new client secret].
Note down your client ID and client secrets. Client secrets will not be displayed again once you navigate away from this page.
5. Update your OAuth SP settings on Kuroco
Return to your Kuroco admin panel. Click [External system integration] -> [OAuth SP] in the sidebar menu.
Click the name of the OAuth SP that you added in Step 2.
Enter the client ID and secret that you noted down in Step 4.
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.
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.
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.
| IdP | URL | Variable names |
|---|---|---|
| GitHub | https://github.com/settings/developers | Client ID, client secret |
| https://console.cloud.google.com/apis/credentials | Client ID, client secret | |
| https://developers.facebook.com/apps | App 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.
You must save your settings before running the test. Unsaved cannot be tested.
Support
If you have any other questions, please contact us or check out Our Slack Community.