This document explains how to implement Monosign with Homer (SIPCAPTURE), the open source SIP and RTC capture and troubleshooting platform. It covers Single Sign-On with OAuth 2.0, which is built into the Homer web application (homer-app). Homer uses the Authorization Code flow with PKCE and reads the user from the user information endpoint, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the homer-app documentation (opens in a new tab).
This configuration was tested with homer-app 1.5.25. If your version is different, please check the Homer documentation.
OAuth 2.0 is configured in the oauth2 section of the file webapp_config.json of Homer. There is no setting screen in the Homer interface. Homer also supports LDAP; SAML is not available.
Monofor has no responsibility to do Homer configurations. If you need support please contact the SIPCAPTURE community or your Homer support provider.
Instructions
This documentation contains 5 main steps for integration.
Creating an application on Monosign
Configuring the OIDC/OpenID settings on Monosign
Assign a user to the Homer application
Configuration Single Sign-On for Homer
Sign In Test
1- Creating an Application on Monosign
Create your application on Monosign first. Open the Applications page from the left menu and click Add New.
Homer is not in the application catalog, so click Create from scratch.
Fill in the application details on the Application tab and click Next.
Property | Value | Description |
|---|---|---|
Name |
| Name of the application shown to users on the Monosign portal and on the Monosign sign-in page. |
Type |
| Homer is accessed through a web browser. Options: Web, Mobile, Desktop, API. |
Url | Optional | Leave empty or enter the address of Homer (for example |
Logo | Optional | Browse and upload a logo; it is also shown on the Monosign sign-in page. |
Users can see this application on their list |
| Displays the application on the user portal. |
On the Access tab define who can reach the application and click Create Application.
Property | Value | Description |
|---|---|---|
User Access Type |
| Defines which users can access this application. Options: Only Assigned Users, All Users, System Default. |
User Group Access Type |
| Defines the application’s user group access. |
Source Using Type |
| Defines which user sources the application can use. |
Profile Access Type |
| Defines which user profile attributes are available to the application (Options: Restricted, All). Homer needs the e-mail address of the user. |
After the application is created, click Keys and add a new Access Key for OIDC/OpenID access.
Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically. Homer consumes the key with OAuth 2.0 and does not read the discovery document, so every address is entered one by one.
Configuration details for the Homer application are provided as follows:
Monosign value | Example | Used in Homer as |
|---|---|---|
Client Id |
|
|
Client Secret |
|
|
Auth Url |
|
|
Access Token Url |
|
|
User Info Url |
|
|
2- Configuring the OIDC/OpenID Settings on Monosign
Open the Keys tab of the application and click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings.
Add the callback address of Homer to Allowed Redirect URIs, enter the scopes in the Scope field, then press Update.
Property | Value | Description |
|---|---|---|
Allowed Redirect URIs |
| The address where Monosign sends the user back after sign-in. |
Scope |
| Enter the three scopes one by one. |
Other fields | Empty / default | The other fields (Issuer, Audience, Resource, token lifetimes, CORS) are not needed. |
3- Assign a User to the Homer Application
Open the application in Monosign, click the Assignments tab and click Assign a User.
Search and select the users who can sign in to Homer, check the Expiration Date and save. You can select more than one user. Every user needs an e-mail address in Monosign, because Homer uses it as the user name.
4- Configuration Single Sign-On for Homer
As we mentioned at the start, please check out the Homer documentation first. Add the section oauth2 to the file webapp_config.json of Homer (in /usr/local/homer/etc), replace the placeholder values and restart Homer. The default configuration file of the Homer Docker image does not contain this section, so the whole block must be added.
"oauth2": {
"enable": true,
"client_id": "<client-id>",
"client_secret": "<client-secret>",
"project_id": "Monosign",
"auth_uri": "https://<monosign-host>/openid/authorize",
"token_uri": "https://<monosign-host>/openid/token",
"profile_url": "https://<monosign-host>/openid/userinfo",
"redirect_uri": "https://<homer-address>/api/v3/oauth2/auth",
"service_redirect": "/api/v3/oauth2/redirect",
"provider_name": "monosign",
"grant_type": "authorization_code",
"response_type": "code",
"auth_style": 1,
"use_pkce": true,
"user_token": "<random-string-of-at-least-43-characters>",
"state_value": "<random-string>",
"scope": ["openid", "profile", "email"]
}
Option | Value | Description |
|---|---|---|
enable |
| Shows the OAuth 2.0 sign-in on the Homer login page. |
client_id and client_secret | Client Id and Client Secret | Copied from the Monosign OIDC/OpenID Access Key Details created in the first step. |
project_id |
| Name of the provider; it is the text of the button on the login page. |
auth_uri, token_uri and profile_url | Monosign addresses | The Auth Url, Access Token Url and User Info Url of the Monosign key (step 1). |
redirect_uri |
| Homer adds |
provider_name |
| Short name of the provider; it is part of the callback address. |
auth_style |
| Sends the client credentials in the token request body. |
use_pkce, user_token |
| PKCE is enabled. Homer uses the fixed value |
state_value | A random string | Fixed value that Homer sends as the OAuth state; use your own random string. |
scope |
| Must be the same as the scopes of step 2. |
Homer reads the e-mail address from the user information of Monosign and uses it as the user name. Users that sign in with OAuth 2.0 get the user group user. The administrator group is given only to users whose e-mail address is registered as an administrator in Homer. When Homer is behind a reverse proxy, the proxy must send X-Forwarded-Proto: https.
5- Sign In Test
Now try to log in to Homer using Monosign SSO. Open a new browser window (or a private window) and type the address of Homer. Below the user name and password form the login page shows the Monosign button (or continue with).
Click the Monosign button once.
On the Monosign sign-in page log in passwordless with your QR code (Monofor Identity), with a Passkey or with your user name and password (Sign in with Password). If you are already signed in to Monosign, the page is skipped.
After the sign-in Monosign redirects the browser back to Homer (
/api/v3/oauth2/auth/monosign) and the user is signed in to Homer.
Troubleshooting
Symptom | Cause | Solution |
|---|---|---|
The Monosign button is not shown | The section | Check step 4 and restart Homer. |
Monosign shows a redirect URI error | The callback address does not exactly match the Allowed Redirect URIs, for example because | Use |
An error appears after returning from Monosign | The Client Id or Client Secret is wrong, or Homer cannot reach Monosign. | Copy the values again from the Monosign access key (step 1) and check that the Monosign addresses open from the Homer server. |
The user signs in but has no administrator rights | Users of OAuth 2.0 get the user group user. | Register the e-mail address of the user as an administrator in Homer. |
A user cannot sign in | The user is not assigned to the application. | Assign the user in step 3. |
After completing the configuration on Homer and Monosign, it is better to test in a new private browser window if the OAuth 2.0 SSO doesn’t work, because old session cookies may cause errors.