Vendor SSO

Enable "Sign in with [Your System]" for your users. Instead of managing separate Unomed credentials, users can authenticate using their existing account in your system.

How It Works

1. User clicks "Sign in with [Your System]" on Unomed login page
2. User is redirected to your OAuth2 authorization endpoint
3. User authenticates with their existing credentials in your system
4. Your system redirects back to Unomed with an authorization code
5. Unomed exchanges the code for an access token
6. Unomed fetches user information from your userinfo endpoint
7. User is logged into Unomed (new account created or existing account linked)

Prerequisites

Your system must support OAuth2 or OpenID Connect (OIDC) with the following endpoints:

• Authorization endpoint (e.g., https://your-system.com/oauth/authorize)
• Token endpoint (e.g., https://your-system.com/oauth/token)
• Userinfo endpoint (e.g., https://your-system.com/oauth/userinfo)

Configuration Exchange

What You Provide to Unomed

Item	Description	Example
Authorization URL	Your OAuth2 authorization endpoint	https://your-system.com/oauth/authorize
Token URL	Your OAuth2 token endpoint	https://your-system.com/oauth/token
Userinfo URL	Endpoint returning user profile	https://your-system.com/oauth/userinfo
Client ID	OAuth2 client identifier for Unomed	unomed_client_abc123
Client Secret	OAuth2 client secret for Unomed	(provided securely)
Scopes	Required OAuth2 scopes	openid email profile
Token Auth Method	How to send credentials to token endpoint	post (default) or basic

What Unomed Provides to You

Configure these redirect URIs in your OAuth2 server:

Environment	Redirect URI
Production	https://api.unomed.ch/accounts/vendor_oauth2/login/callback/
Development	https://api.dev.unomed.ch/accounts/vendor_oauth2/login/callback/

OAuth2 Specification

This section details the exact requests and responses your OAuth2 server must handle.

Step 1: Authorization Request

When a user initiates login, Unomed redirects to your authorization endpoint:

GET https://your-system.com/oauth/authorize?
    response_type=code&
    client_id=unomed_client_abc123&
    redirect_uri=https://api.unomed.ch/accounts/vendor_oauth2/login/callback/&
    scope=openid%20email%20profile&
    state=random_state_string

Parameter	Description
response_type	Always code (Authorization Code flow)
client_id	The client ID you provided to Unomed
redirect_uri	Unomed's callback URL (must match exactly)
scope	Space-separated scopes (URL-encoded)
state	Random string for CSRF protection (must be returned unchanged)

Step 2: Authorization Response

After the user authenticates, redirect back to Unomed with the authorization code:

HTTP/1.1 302 Found
Location: https://api.unomed.ch/accounts/vendor_oauth2/login/callback/?
    code=AUTHORIZATION_CODE&
    state=random_state_string

Parameter	Description
code	The authorization code (single-use, short-lived)
state	The same state value from the request

If the user denies access or an error occurs:

Location: https://api.unomed.ch/accounts/vendor_oauth2/login/callback/?
    error=access_denied&
    error_description=User%20denied%20access&
    state=random_state_string

Step 3: Token Request

Unomed exchanges the authorization code for an access token.

Client Authentication Methods

Your token endpoint must support one of these client authentication methods:

Option A: Client Secret Post (default)

Client credentials are sent in the request body:

POST https://your-system.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://api.unomed.ch/accounts/vendor_oauth2/login/callback/&
client_id=unomed_client_abc123&
client_secret=YOUR_CLIENT_SECRET

Option B: Client Secret Basic

Client credentials are sent in the HTTP Authorization header (Base64-encoded):

POST https://your-system.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dW5vbWVkX2NsaWVudF9hYmMxMjM6WU9VUl9DTElFTlRfU0VDUkVU

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://api.unomed.ch/accounts/vendor_oauth2/login/callback/

Tell Unomed which method your server supports when providing your configuration.

Step 4: Token Response

Return a JSON response with the access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Field	Required	Description
access_token	Yes	Token to access the userinfo endpoint
token_type	Yes	Must be Bearer
expires_in	No	Token lifetime in seconds

Step 5: Userinfo Request

Unomed fetches user details using the access token:

GET https://your-system.com/oauth/userinfo
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Step 6: Userinfo Response

Return a JSON object with user details (standard OIDC claims):

{
  "sub": "unique-user-id-123",
  "email": "user@example.com",
  "given_name": "John",
  "family_name": "Doe",
  "preferred_username": "johndoe",
  "picture": "https://your-system.com/avatars/johndoe.jpg"
}

Required Fields

Field	Description
sub or id	Unique user identifier in your system

Strongly Recommended Fields

Field	Description
email	User's email address

Note: If the email field is missing from your userinfo response, users will be redirected to a profile completion form where they must provide their email address (which will be verified via OTP). This creates additional friction, so providing the email is strongly recommended.

Optional Fields

Field	Description
given_name or first_name	User's first name
family_name or last_name	User's last name
preferred_username	Preferred username
picture	URL to user's avatar image

User Account Linking

When a user signs in via your system:

• New user: A new Unomed account is created automatically using the email and name from your userinfo response
• Existing user: If a Unomed user with the same email already exists, the accounts are automatically linked

Implementation Checklist

Use this checklist to implement Vendor SSO:

• [ ] Set up OAuth2/OIDC server with authorization, token, and userinfo endpoints
• [ ] Create an OAuth2 client for Unomed with client_id and client_secret
• [ ] Allowlist Unomed redirect URIs in your OAuth2 server
• [ ] Configure userinfo endpoint to return required fields (sub, email)
• [ ] Send configuration details to info@unomed.ch
• [ ] Test the integration in development environment
• [ ] Test the integration in production environment

Security Considerations

• Use HTTPS for all OAuth2 endpoints
• Keep the client secret secure and never expose it in client-side code
• Authorization codes should be single-use and short-lived (recommended: 10 minutes)
• Implement proper token expiration and rotation
• Validate the redirect_uri parameter exactly matches the registered URI
• Consider implementing PKCE for additional security

Troubleshooting

Common Errors

Error	Cause	Solution
"Provider not found"	Invalid or inactive provider_id	Verify your provider_id with Unomed
Redirect loop	Incorrect redirect_uri configuration	Ensure redirect_uri matches exactly, including trailing slash
"Invalid grant"	Authorization code expired or already used	Codes are single-use; restart the flow
User not created	Missing required fields in userinfo	Ensure userinfo returns sub (or id) and email
"Invalid token"	Token expired or malformed	Check token endpoint returns valid access_token

Testing Your Endpoints

You can test your OAuth2 endpoints independently:

Test token endpoint:

curl -X POST https://your-system.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Test userinfo endpoint:

curl https://your-system.com/oauth/userinfo \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Testing the Integration

1. Contact info@unomed.ch to have your provider configured in our development environment
2. Navigate to:

   https://api.dev.unomed.ch/accounts/vendor_oauth2/login/?provider_id=YOUR_PROVIDER_ID
   

3. You should be redirected to your authorization endpoint
4. After authentication, you should be redirected back and logged into Unomed
5. Verify the user account was created with correct email and name

Next Steps

Once Vendor SSO is configured, you can combine it with the PopApp integration to provide a seamless experience where users authenticate once in your system and access Unomed without additional login steps.