General OIDC Platform Integration

0 11 April 2024

This guide will help you with the basics of integrating ALMEFY as Single Sign-On (SSO) provider using the OpenID Connect (OIDC) standard on platforms that support the standard.

This process involves creating an OIDC Endpoint in the ALMEFY Hub. Endpoints act as connectors between ALMEFY and your platforms like Salesforce, Office 365 or WordPress.

OIDC is an open standard, meaning it is implemented in a large number of platforms for which we do not have tailored guides yet.
Since the process is standardized it is similar on most platforms and this guide should provide what you need to get started.

Prerequisites

  1. Admin access to your platform.
  2. Ensure the platform supports the OpenID Connect standard.
  3. An active ALMEFY account with admin access to https://<subdomain>.hub.almefy.com.

2: This information can be typically found on the platforms product page, it's documentation pages or somewhere in the admin settings under "Authentication", "Login" or "Single Sign-On (SSO)".

Setup

The steps in this guide correspond to the steps in left column of the ALMEFY Hub endpoint configuration.

  1. Configure Endpoint
  2. Configure Platform
  3. Copy metadata provided by the platform.

Step 1: Create and Configure Endpoint in ALMEFY Hub

  1. Log in to your ALMEFY Hub account at https://<subdomain>.hub.almefy.com.

  2. In the ALMEFY Hub dashboard, navigate to the "Endpoints" section.

  3. Click on "Add Endpoint"

  4. Select "OIDC Endpoint".

  5. Fill in the required information

At minimum, an OIDC Endpoint requires:

Name
Used to identify the platform. Choose a name users will easily recognize.

Endpoint ID
A unique identifier for this endpoint you will later enter in the platforms settings.

Endpoint URI
In order to initiate the login flow from the ALMEFY SSO page a starting point is required. For this you must provide the login page of your platform. For example https://<yourwebsite>.com/login.

You can find your ALMEFY SSO page at https://<subdomain>.sso.almefy.com.

Grant Types
ALMEFY currently supports the 'Authorization Code' grant type for web apps with server-side handling. Further types will be added in the near future.

Response Types
ALMEFY currently supports the 'Code' response type designed for server-side authentication, involving a backend.
Further types will be added in the near future.

Secret
The secret ensures the communication between ALMEFY and your plafform remain secret.
You can set your own secret or click the generate button below the input.

Optional Settings
You may open the optional section and adjust additional settings such as session lifetimes and access requirements.

  1. Move on to the next step before saving the new endpoint.

Step 2: Configure Your Platform

  1. Keep the ALMEFY Hub open and log in to your platform's admin dashboard.

  2. Locate and access the settings or authentication section on your platform.

  3. Look for an option to configure SSO, OIDC or OAuth 2 authentication.

  4. The OIDC settings on your platform will require you to copy some settings and URIs provided in Step 2. in the ALMEFY Hub. Click the copy buttons to copy the contents to your clipboard and paste them into your platform settings. The available fields are further described in the ALMEFY Hub.

If you find your platform to require metadata that is currently not yet provided or supported by ALMEFY contact our support for further assistance.

Step 3: Copy Configuration from your Platform

  1. Your platform should now also provide a set of links that are required by the step 3 section in the ALMEFY Hub. Copy these over.

Redirect URI
Required
Your platform will provide a redirect URI that will be called by ALMEFY every time a login request has been authenticated.

Post Logout Redirect URI
This is an optional URI linking to a page where users are redirected to after being logged out.

  1. Confirm and save the settings in both the ALMEFY Hub as well as your platofrms OIDC settings page.

Step 4: Test OIDC Login

You will have to assign your new Endpoint to a group and add your user to that group as well, to make sure you can test the login.

  1. Visit your platform's login page.

  2. You should now see the "Login with ALMEFY" or "Login with OIDC" button.

    • Example:
      Example

  3. Click "Login with ALMEFY".

  4. You will be redirected to an ALMEFY SSO page which contains the ALMEFY Login QR Code.

  5. Scan the code using the ALMEFY App.

Please make sure you enrolled your device before trying to log in. You can do so by managing your user in the ALMEFY Hub > Users > Settings section.

  1. Once authenticated, you will be redirected back to your platform, logged in automatically.

Troubleshooting

If you encounter any issues during the setup, please follow these steps:

  1. Refer to your platform's documentation: Check your platform's official documentation for troubleshooting guidance related to OIDC authentication or SSO configuration.

  2. Contact your platform's support team: Reach out to your platform's support team for platform-specific assistance and troubleshooting. They can provide guidance tailored to your platform's setup.

  3. ALMEFY Support: If you're unable to resolve the issue with your platform's documentation and support, don't hesitate to seek help from the ALMEFY support team. We're here to assist you in configuring OIDC authentication with ALMEFY as the identity provider.

    Contact Almefy Support: Reach out to us via our contact form for assistance with OIDC setup issues. Please provide detailed information about the problem you're facing, and our support team will be happy to assist you.

Conclusion

Congratulations! You've successfully set up OIDC authentication for your platform using ALMEFY as the identity provider. Your users can now enjoy secure and convenient single sign-on.