ASP.NET OAuth Single Sign-On (SSO) using Keycloak as OAuth Provider

ASP.NET OAuth Single Sign-On (SSO) module gives the ability to enable OAuth Single Sign-On for your ASP.NET applications. Using Single Sign-On you can use only one password to access your ASP.NET application and services. Our module is compatible with all the OAuth compliant Identity providers. Here we will go through a step-by-step guide to configure Single Sign-On (SSO) between ASP.NET and Keycloak as OAuth Provider.

Pre-requisites: Download And Installation

• Download miniOrange ASP.NET OAuth 2.0 Module.
• For Setting up the connector, extract the asp-net-oauth-sso-module.zip, you will find a DLL file miniorange-oauth-sso.dll, a configuration file oauthsso.config and a integration.md file which contain the steps for adding the module into your application.

1. Add the connector in your application

• Add miniorange-oauth-sso.dll in bin folder (where your other DLL files exists) for your application.
• Register miniorangeoauthsso module in your application according to the provided steps in the integration.md file.
• Add the provided configuration file oauthsso.config in the root directory for your application.
• After integration open browser and browse the connector dashboard with URL below:
  https:// <your-application-base-url>/?ssoaction=config
• If it pop up the registration page or login page, you have successfully added the miniOrange oauth sso connector for your application.

• Register or Login for configuring the connector.

2. Setup Keycloak as OAuth Provider

• First of all, Download Keycloak and install it.
• Start Server: Start the keycloak server by running the _standalone.sh_ file.
Root Directory of keycloak bin standalone.sh

• Version 18 and below
• Version 19 and above

Add Realm : Now login to keycloak administration console and navigate to your desired realm. You can add new realm by selecting Add Realm option.

Create realm: Enter Realm Name and keep the realm name handy as it will required later to configure the Realm under the ASP.NET OAuth plugin. Click on CREATE to add realm.

Create OpenID client: Click on the Clients and choose create to create a new client. Enter client id and select client protocol openid-connect and select Save.

Change Access type: After client is created change its access type to confidential.

Enter Valid Redirect URIs: Copy Callback URL from plugin and then click on SAVE. Ex -- https:///oauth/callback

Get Client Secret: Now we need to get client secret. So select Clients and select credentials and copy your secret from here.

Plugin Configuration: Enter copied Client Secret under Client secret field in the ASP.NET OAuth plugin, and enter the Client Name under the Client ID field.
Add User: We need to add users to realm who will be able to access the resources of realm. Click on the Users and choose to Add a new User.

User Configuration: After user is created following action needs to be performed on it.
1) Setting a password for it so click on Credentials and set a new Password for the user.


NOTE : Disabling Temporary will make user password permanent.
Map User: We need to map user to a role. Click on Role Mappings and assign the user desired role from available roles and clicking on add selected.

Create ROLE: The Role will be used by your applications to define which users will be authorized to access the application. Click on the Roles and choose Add Role.

Step 2.1: Steps to fetch Keycloak Groups
• Create groups: Click on the Groups and choose New to create a new group.

• Assign user to group: Select the user whom you want to add in group. Choose Groups option from tab and then select the group-name and click on join.

• Keycloak Group Mapper: Now to get group details we need to perform its client mapping with group membership else group details will not be fetched. So in Client section, select your client and then click on mapper->create.

• Now, select mapper type as Group Membership and enter the name and token claim name i.e the attribute name corresponding to which groups will be fetched. Turn Off the full group path, Add to ID token and Add to access token options, and click on Save.


Note: -- If full path is on group path will be fetched else group name will be fetched.
Step 2.2: Steps to fetch Keycloak Roles
• Keycloak Role Mapper: Now to get role details we need to perform its client mapping with role membership else role details will not be fetched. So in Client section, select your client and then click on mapper->create.

• Now, select mapper type as user realm Role Membership and enter the name. and token claim name i.e the attribute name corresponding to which groups will be fetched. Add to ID token and Add to access token options, and click on Save.

Add Realm : Now login to keycloak administration console and navigate to your desired realm. You can add new realm by selecting Create Realm option.

Create realm: Enter Realm Name and keep the realm name handy as it will required later to configure the Realm under the OAuth Client plugin. Click on CREATE to add realm.

Create OpenID client: Click on the Clients and choose Create Client to create a new client. Enter Client ID and select client protocol openid-connect and Click Next.

Enable the Client Authentication and Authorization toggle.

Scroll down to the Access settings and enter your Callback/Redirect URL which you will get from your miniOrange plugin present on your Client side under the CallBack URLs text-field.

Go to the Credentials tab, copy the Client Secret and keep it handy as we will require it later while configuring ASP.NET OAuth Single Sign-On plugin.

Plugin Configuration: Enter copied Client Secret under Client secret field in the ASP.NET OAuth plugin, and enter the Client ID under the Client ID field.
Add User: We need to add users to realm who will be able to access the resources of realm. Click on the Users and Click on Create new user to Add a new User.

User Configuration: After user is created following action needs to be performed on it.
1) Setting a password for it so click on Credentials and set a new Password for the user.


NOTE : Disabling Temporary will make user password permanent.
Map User: We need to map user to a role. Click on Role Mappings and assign the user desired role from available roles.

Create ROLE: The Role will be used by your applications to define which users will be authorized to access the application. Click on the Roles and choose Create Role.

3. Configure miniOrange ASP.NET OAuth Client

• After configuring your OAuth Provider, it will provide you with Client ID, Client Secret, Authorize Endpoint, Access Token Endpoint and Get User Info Endpoint. Configure these values under respective fields.
• Fill all the required details and click on Save Configuration.

4. Test Configuration

• After saving configuration, click on the Test Configuration button to verify if you have configured correctly.
• On successful configuration, you will get Attributes Name and Attribute Values on Test Configuration window. The below screenshot shows a successful result.
• 

5. Attribute Mapping

• Map Attribute Names provided by your OAuth Server with your ASP.NET application Attributes given under Attribute Mapping Section and click on Save Attribute Mapping.

• Note: All the mapped attributes will be stored in the session so that you can access them in your application.

6. Integration Code

• You can find the integration code in Integration Code tab in the connector. Just copy-paste that code snippet wherever you want to access the user attributes.

7. Add following link in your application for Single Sign-On (SSO)

• Use the following URL as a link in your application from where you want to perform SSO:
  http://base-url/?ssoaction=login
• For example you can use it as:
  <a href="http://base-url/?ssoaction=login”>Log in</a>"

You can configure the ASP.NET SAML 2.0 Single Sign-On (SSO) module with any Identity Provider such as ADFS, Azure AD, Bitium, Centrify, G Suite, JBoss Keycloak, Okta, OneLogin, Salesforce, AWS Cognito, OpenAM, Oracle, PingFederate, PingOne, RSA SecureID, Shibboleth-2, Shibboleth-3, SimpleSAML, WSO2 or even with your own custom identity provider.