Umbraco OAuth Single Sign-On (SSO) Setup Guides
Choose your SAML identity provider to configure Single Sign-On (SSO)
Not able to find your IdP? Contact us at umbracosupport@xecurify.com and we will help you setup Umbraco SSO with your IdP in no time.
Couldn't find your IdP?
Reach out to us at umbracosupport@xecurify.com and we will help you setup Umbraco SSO with your identity provider (IdP) in no time.
Setup Guide
Steps to Configure the Umbraco OAuth/OpenID Connect (OIDC) Middleware
Configuring the Umbraco OAuth/OpenID Connect (OIDC) middleware will allow you to connect any OAuth 2.0/OIDC compliant authentication provider with your Umbraco application to perform Single Sign-On (SSO), to authenticate and authorize the user. You can follow below mentioned steps to configure the middleware to set up Single Sign-On service via OAuth 2.0/OIDC enabled for your application.
Step 1: Download and extract the package
- Download the Umbraco OAuth/OIDC middleware.
- For setting up the middleware, extract the umbraco-oauth-oidc-single-sign-on.zip you will find a DLL file called miniorange-oauth-oidc-sso.dll, and a folder called miniOrange-sso-configuration that contains a configuration file called configuration.json.
Step 2: Add middleware to your Umbraco application
- Add the miniorange-oauth-oidc-sso.dll reference in your Umbraco application.
- Add the miniOrange-sso-configuration folder to the root folder of your Umbraco application.
- In the Startup.cs file:
-
Add the namespace miniOrange.oauth
using miniOrange.oauth; -
Update the Umbraco middleware snippet lines in the Startup class,
configure method as below:
app.UseUmbraco()
.WithMiddleware(u => {
u.UseBackOffice();
u.UseWebsite();
u.AppBuilder.UseminiOrangeOAuthOIDCSSOMiddleware();
})
.WithEndpoints(u => {
u.UseInstallerEndpoints();
u.UseBackOfficeEndpoints();
u.UseWebsiteEndpoints();
}); - Run the Umbraco application when the configuration is done.
-
After integration, open your browser and browse the middleware dashboard
with the URL below:
https://<umbraco-application-base-url>/?ssoaction=config - If the registration page or login page pops up, you have successfully added the miniOrange Umbraco OAuth/OIDC middleware to your Umbraco application.
Step 3: Configure the OAuth/OIDC provider
- To create a connection between your OAuth/OIDC Provider and your Umbraco application, you have to configure your OAuth/OIDC provider in the middleware.
- Click on the OAuth/OIDC Applications from the navigation bar.
- Click on the Add New Provider button .
- Select your OAuth provider from the Provider List.
- Note: If you can not find your provider in the list, you can always go with the Custom OAuth 2.0 App or Custom OpenID Connect App.
- Copy the Redirect/Callback URL from the plugin and provide it to your OAuth provider to configure it on their side.
- When you are done configuring your identity/OAuth provider, you will get Client ID, Client Secret and all required authentication endpoints.
- Fill the rest acquired details into the corresponding fields.
- Depending on the selected OAuth provider the protocol options are enabled, i.e. OAuth or OpenID Connect.
- If you wish to perform OAuth SSO with a protocol that is disabled, feel free to select the custom provider app for this configuration.
- Check all the required details and click on Save.
Step 4: Testing OAuth SSO
- After saving the configuration, click on the Test Configuration button to verify if you have configured your OAuth/OIDC provider correctly.
- On successful configuration, you will get attribute names and attribute values on the test configuration window. The below screenshot shows a successful result.
- In case you didn't receive the required details or attributes from your authentication provider based on the configured scopes, reach out to us at umbracosupport@xecurify.com
Step 5: Select User Login Type
- After the successful test configuration, in the same Provider Settings tab, go to the User Login Type settings.
- Select the User SSO login type based on your requirement, i.e. which type of user is going to perform Single Sign-On login, you may select either BackOffice Login or Member Login and click on Save.
Step 6: Attribute/Role Mapping
- To perform the Single Sign-On login, you need to map the received attribute from the provider to identify the user.
- Go to the Attribute/Role Mapping tab for further configurations.
- In this trial, you would be able to configure the required attributes only, i.e. username and email. Fill in the username and email field with the name of the attribute, you will be receiving. Then, click Save.
- In this trial, you would also be able to configure the default role for the user. In the same tab, you can select the default role from the dropdown field names Default Role. The options listed in the dropdown menu are based on the SSO Login type you have selected.
- If you are not able to find the list of roles, please check in the Umbraco BackOffice, if you have roles present there or not for the selected SSO Login Type.
- After selecting the roles carefully, click Save.
- Note: This is one of the crucial steps during single sign-on configuration, if you are not able to complete this step or facing any difficulties in understanding the steps, feel free to reach out to us at umbracosupport@xecurify.com.
Step 7: Get the link for SSO and SLO for your Umbraco application
- When all the necessary configuration is completed, you can perform single sign-on through the SSO link.
- You can find the SSO Link in the action dropdown in the application list tab of the middleware.
- Similarly, you can find the single logout (SLO) link in the action dropdown.
You can even configure the Umbraco 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. To check other identity providers, click here.
Need Help?
Not able to find your identity provider? Mail us on umbracosupport@xecurify.com and we'll help you set up SSO with your IDP and for quick guidance (via email/meeting) on your requirement and our team will help you to select the best suitable solution/plan as per your requirement.
Need Help? We are right here!
