Configure SSO

Duration40 minLevelAdvancedOfferOffre de basePrerequisitesLesson 5

Objectives

• I understand the role of VaultysHub as an identity provider (IdP)
• I know how to choose between OIDC and SAML 2.0 in the Authentication tab
• I know what information to exchange between VaultysHub and the application
• I have connected an application using OIDC and logged in via VaultysHub
• I know how to pass user groups to the application
• I know how to diagnose the most common errors

0 / 6 objectives achieved — check them off as you go through the lesson.

Why it's useful

Comptalys hosts a Grafana dashboard that tracks the activity of the firm. Until now, each partner had an account and an additional password. Karim connects it to VaultysHub using OpenID Connect: partners click on the Grafana tile and are logged in, without entering anything. When a partner leaves the firm, simply deactivating them in VaultysHub is enough.

With SSO, the application delegates authentication to VaultysHub. Your users log in once, with VaultysID, and access all their applications. SSO is part of the basic offering, in OpenID Connect as well as in SAML 2.0.

The two protocols at a glance

	OpenID Connect (OIDC)	SAML 2.0
For	Modern and cloud applications	Established enterprise applications
What VaultysHub provides	Endpoints (Discovery, Authorization, Token, JWKS, Userinfo) and a Client Secret	Entity ID, SSO URL, Metadata URL (in the Identity Provider tab)
What you enter in VaultysHub	The application's Redirect URIs and Allowed Scopes	Entity ID, ACS URL and application certificate (in the Service Provider tab)

The details of each field can be found in SSO Configuration.

Your turn: Grafana with OIDC

This exercise follows the guide Grafana. You need a Grafana instance where you are an administrator. If you don't have one, perform the exercise with another application from the appendix: the steps on the VaultysHub side are the same.

1. Create the application Grafana in Applications, with the URL of your instance. See lesson 5.

2. Choose the protocol. Menu ⋮, Edit, Authentication tab: select OIDC.

3. Take note of the information from the Provider Settings tab: endpoints, client ID, and Client Secret. Leave PKCE enabled, it is recommended.

4. Declare the return URL in Redirect URIs: https://grafana.example.com/login/generic_oauth, replacing the domain with that of your instance. Keep the scopes openid, profile, and email.

5. Configure Grafana. In the auth.generic_oauth section of grafana.ini, fill in the client ID, secret, and the three URLs auth_url, token_url, and api_url:

   [auth.generic_oauth]
   enabled = true
   name = VaultysHub SSO
   allow_sign_up = true
   client_id = <client ID>
   client_secret = <client secret>
   scopes = openid profile email
   auth_url = https://<your-organization>/api/oidc/<appid>/auth
   token_url = https://<your-organization>/api/oidc/<appid>/token
   api_url = https://<your-organization>/api/oidc/<appid>/userinfo
   use_pkce = true

   The Client Settings tab of VaultysHub also provides a ready-to-use code example.

6. Share the application with your test folder, as in lesson 5. Without sharing, the user will be denied access.

7. Test. Restart Grafana, click on Sign in with VaultysHub SSO and authenticate with VaultysID.

8. Go further with groups. In the Authentication tab, Groups section, click on Add a mapping, associate a folder with a group from the application, check Send groups and Save mappings. On the application side, add groups to the requested scopes. See Groups.

The most common errors

• Invalid redirect URI: the return URL must be strictly identical on both sides. Pay attention to the trailing slash and http vs https.
• Invalid client credentials: check the client ID and secret.
• User not authorized: the user does not have access to the application. Check the sharing.

See Support and troubleshooting.

And in SAML?

The process is symmetrical. You copy the information from the Identity Provider tab of VaultysHub into the application: Entity ID, SSO URL, or directly the Metadata URL. You enter in the Service Provider tab the information from the application: Entity ID, ACS URL, certificate. Single Logout from VaultysHub is not supported.

Check your understanding

1In an SSO configuration, what is the role of VaultysHub?

2Grafana returns Invalid redirect URI. What do you check first?

3The configuration is correct but a collaborator gets User not authorized. Why?

4In SAML, what information do you copy from VaultysHub to the application?

5In OIDC, what is needed for the application to receive user groups?

Key takeaways

• VaultysHub is the identity provider: the application delegates the connection to it, in OIDC or SAML.
• A successful configuration relies on an exchange of information on both sides, and on an exact return URL.
• SSO respects sharing: access is granted through folders, as with any application.

Appendix: integration guides

Step-by-step guides exist for many applications. See the SSO Integrations page for an overview and generic endpoints.

Domain	Guides
Collaboration and cloud	Nextcloud, GitLab, Trello, Notion, Monday.com
Infrastructure and network	Tailscale, Headscale, Apache Guacamole, Proxmox VE, Portainer
Monitoring	Grafana
Communication	Mattermost, Rocket.Chat, BlueMind
ERP and CRM	Odoo, Dolibarr, EspoCRM, HubSpot
Support and management	GLPI, Zammad
Security	Vaultwarden
HR	Lucca

Next lesson: Manage your users' devices