Skip to main content

· 11 min read
Dr. Mattia Zago

Monokee's partner: Toothpic

Toothpic stands at the forefront of revolutionary authentication technology, introducing a cutting-edge approach that leverages the unique hardware characteristics of smartphones for unclonable identity verification. At its core, Toothpic addresses the escalating challenges of traditional authentication methods and forges a path towards a frictionless, passwordless identity and access management (IAM) framework.

The heart of Toothpic's innovation lies in its utilization of the camera sensor's fingerprint, an inherent and indelible trace known as PRNU (Photo-Response Non-Uniformity). This fingerprint, akin to a biological fingerprint, is specific to each device and entirely random, rendered immutable by the manufacturing processes. Capitalizing on this characteristic, Toothpic crafts a secure linkage between cryptographic keys and the sensor hardware, resulting in an unhackable, unclonable identity unique to every individual device.

By integrating Toothpic's technology into Monokee, enterprises unlock a realm of benefits. Password fatigue, susceptibility to phishing, and the vulnerabilities of shared secrets are swiftly eradicated. Users authenticate themselves using their smartphones, their digital extensions, free from the inconvenience of passwords, tokens, or OTPs. Toothpic's asymmetric cryptography ensures the private key remains exclusively on the device, fostering heightened security by eliminating shared points of compromise.

The Key Protection SDK exemplifies Toothpic's commitment to robust security. It safeguards cryptographic keys against malware and unauthorized access, coupling them with the camera sensor's fingerprint. This secure hardware key paradigm drastically minimizes attack vectors, solidifying the shield against contemporary threats.

In a world where identity breaches loom large and user experience is paramount, Toothpic presents a transformative solution. It reshapes authentication into a process as natural as the touch of a finger, bolstering security without compromising convenience. The amalgamation of camera fingerprinting, asymmetric cryptography, and secure computation constructs a formidable fortress around digital identities. Toothpic is not merely a technology; it is a paradigm shift in the pursuit of a secure, passwordless future.

Toothpic Technology
Figure 1 - Toothpic technology

Use case

Integrating Toothpic's pioneering authentication technology with Monokee's advanced IAM framework establishes a powerful solution for enterprises. This collaboration presents a seamless and frictionless access login for users while maintaining compatibility with SAML, OAuth/OpenID Connect, and legacy systems. Toothpic's hardware-based authentication eliminates passwords, enhancing security and convenience. Leveraging Monokee's Visual Identity Orchestrator, users authenticate effortlessly using their smartphone's unique attributes.

This integration extends beyond simplicity, enabling Monokee to deploy passwordless strong Multi-Factor Authentication (MFA) across applications.

Enterprises benefit from enhanced security without compromising user experience. With Monokee's readiness for Self-Sovereign Identity (SSI), this collaboration offers a future-proof solution that aligns with industry trends. In a landscape demanding robust security and streamlined experiences, the Toothpic-Monokee integration redefines access management, empowering enterprises to embrace a passwordless, secure, and user-centric approach.

The following sequence diagram depicts the interaction between an End-User, the Toothpic system, and the Monokee IAM framework during an authentication process. In this sequence, the End-User interacts with both the Toothpic system and the Monokee IAM framework to securely authenticate themselves using Toothpic's hardware-based authentication. The integration of these systems ensures a seamless and secure user experience throughout the authentication process.

  1. The process begins with the End-User visiting the login page of an application that is integrated with the Monokee IAM framework.
  2. Monokee responds by displaying a QRCode to the End-User on the login page.
  3. The End-User then uses their smartphone's Toothpic app to scan the displayed QRCode.
  4. Toothpic receives the QRCode scan and initiates its internal process. It generates a cryptographic key and proceeds to authenticate the request.
  5. Toothpic communicates with its own components, generating the necessary authentication payload and completing the user's authentication process.
  6. Toothpic forwards the authentication payload to the Monokee IAM framework, indicating that the user's authentication has been successfully completed.
  7. Monokee processes the authentication payload received from Toothpic and confirms the validity of the authentication.
  8. Monokee responds to the End-User, confirming that a new authenticated session has been established.

Technical challenges

Defining a suitable challenge for the integration between Toothpic and Monokee is a critical step to ensure the security of the authentication process. The process will be subject to a series of threats:

  • Replay Attacks: By including a nonce (a random value generated for each challenge), Monokee ensures that each authentication attempt has a unique challenge. This prevents attackers from intercepting and reusing a previously captured challenge to gain unauthorized access.
  • Man-in-the-Middle (MitM) Attacks: Including the issuer and intended audience in the challenge allows Monokee to validate the authenticity of the parties involved. This prevents attackers from intercepting communication between the user and Monokee, as any alteration of the challenge by an attacker would be detected during verification.
  • Callback URL Spoofing: Including the callback URL in the challenge ensures that the response is sent back to the legitimate source. Attackers attempting to redirect the response to a malicious site would be thwarted because the callback URL wouldn't match the legitimate domain.
  • Session Hijacking: The session identifier included in the challenge enables Monokee to tie the authentication request to a specific session. If an attacker manages to intercept the challenge but lacks the valid session identifier, the authentication attempt would fail.
  • Token Theft: Including all the specified components in the signed challenge ensures that the generated tokens are tightly bound to the original request. Even if an attacker manages to gain access to a token, they cannot use it maliciously without knowing the original challenge components.
  • Token Substitution: The signed challenge prevents attackers from substituting a legitimate token with a forged one. Any unauthorized modification to the challenge, including the nonce or session identifier, would result in an invalid signature, rendering the token useless.
  • Token Misuse: Including the intended audience (recipient) in the challenge strengthens security by ensuring that the generated tokens can only be used with the intended system or service, reducing the potential for misuse.

By incorporating these elements into the challenge and ensuring they are properly signed and verified, Monokee can effectively mitigate a wide range of potential attacks, including replay attacks, MitM attacks, spoofing, session hijacking, and various forms of token-based attacks. This comprehensive approach enhances the overall security posture of the authentication process and guarantees a higher level of trust for users.

As such, the challenge should be a JSON Web Token (JWT) build as follows:

Header {
jwk: <Monokee public key>
}.
Payload {
nonce: <rnd>,
aud: <APK id>,
iss: "https://toothpic.monokee.com",
exp: 3600
iat: <issue time>
jti: <session id>
azp: <APK id>,
callback: "https://toothpic.monokee.com/webhook/[...]"
}.
Signature

Adding the request type (approval or signature) and the Key ID (kid) to the challenge is crucial for enhancing the security, control, and flexibility of the integration between Toothpic and Monokee. Here's why this addition is necessary and how it affects different scenarios: The inclusion of the request type (approval or signature) allows Monokee to distinguish between two distinct scenarios: one where a specific secure hardware approval is required (approval request), and the other where any available key can be used for signing (signature request). This differentiation ensures that the appropriate authentication process is triggered based on the specific needs of the scenario.

  1. Controlled Hardware Approval (Approval Request): In cases where a specific secure and controlled hardware approval is necessary, Toothpic can sign the challenge with a default key (identified by a kid or a JWK thumbprint). This action signifies that a designated hardware device has approved the authentication request. Monokee can then recognize this signature and authentication as originating from an authorized and verified hardware device, adding an extra layer of trust to the process. This scenario is particularly useful in contexts where stringent hardware-based security is required.

  2. Flexible Key Usage (Signature Request): When requesting a signature for the challenge without specifying a particular key (signature request), the public key used to sign the challenge becomes the identifier for the user in Monokee. This approach allows for more flexibility in the authentication process, as any key associated with the user can be used to sign the challenge. It accommodates scenarios where the user might have multiple keys or devices for authentication.

The JWT should thus include two additional claims:

  req_type: <approval|signature>
kid? <kid requested for approval>

By embedding the request type and kid in the challenge, the integration between Toothpic and Monokee gains granularity and versatility in managing authentication scenarios. It empowers both systems to cater to different use cases, ensuring optimal security and user experience in various contexts. For example:

  • Enhanced Security for Controlled Devices: Adding the request type and kid can be pivotal in scenarios where only specific hardware devices (approved by Toothpic) are authorized for certain operations. This ensures that the authentication process is tied to trusted, controlled, and secure devices.

  • Multi-Key User Authentication: The inclusion of the request type and kid also caters to users who possess multiple keys for authentication. This flexibility allows users to choose the appropriate key for signing based on the context or device they are using.

  • Adaptive Authentication: Monokee can adapt its authentication flow based on the request type and kid. For example, if an approval request is received, Monokee can implement more stringent security measures due to the controlled hardware approval process.

Solution

By splitting the process into two user journeys, Monokee efficiently manages both the initial authentication flow and the subsequent callback communication. This approach enhances security by allowing Monokee to handle and verify the signed challenge separately from the session unlocking process. It also ensures a seamless and orchestrated experience for the end-user, where authentication and session access are managed in a coherent and secure manner.

Authentication Flow

  1. Challenge Creation: Monokee generates a unique challenge that includes the necessary components such as nonce, issuer, callback URL, intended audience, and session identifier.

    Monokee Create Challenge
    Figure 2 - Monokee Create Challenge

    Example of generated JWT:

    eyJhbGciOiJFUzI1NiIsImp3ayI6eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6Im1EV3hkSFRjT0hXMm44UFVyNkJ2QWlFaTIteEhqZ2Q2TndnakZCSFF5cTgiLCJ5IjoicDVGaUUxYTlFeXNXNFY1NlJvQlFGb1BFMUNXRTREUzRHMmtXS0dDQnZ1ZyIsInVzZSI6InNpZyIsImFsZyI6IkVTMjU2Iiwia2lkIjoiZGYzNDU1MmUtNzIxZi00ZTUxLWEzZDctNDcwMzE0N2Y3ZjViIn19.eyJjYWxsYmFjayI6Imh0dHBzOi8vdG9vdGhwaWMubW9ub2tlZS5jb20vd2ViaG9vay8_Zmxvd19pZD0yMDQ0ZWEzNy0yYjg1LTQzYTYtYjA0Yy0xY2ZjZTVjMmE5NjgiLCJub25jZSI6IjE3NTM2ZGU1LWE3MjMtNGFkNC04MWYyLTk1NjUzZjQzNjRkYSIsImF6cCI6ImNvbS50b290aHBpYy50b290aHBpY21vbm9rZWUiLCJqdGkiOiI3YjM5OTZjOC04YjA5LTQ5NzktYThkMC0yMmQyNWY2Y2EzZGEiLCJpYXQiOjE2OTExNDQ2MDAsImlzcyI6Imh0dHBzOi8vdG9vdGhwaWMubW9ub2tlZS5jb20iLCJhdWQiOiJjb20udG9vdGhwaWMudG9vdGhwaWNtb25va2VlIiwiZXhwIjoxNjkxMTQ1MjAwfQ.JeH1_L8TkWcd8DuERfrF1f3hh9AjZDe0KVfBVwgLoqLoLB0TN5Za5RFWZzt6qEYz-UO_bIrOY4MaA8Ry1pA1KA

    Which decodes to:

    {
    "alg": "ES256",
    "jwk": {
    "crv": "P-256",
    "kty": "EC",
    "x": "mDWxdHTcOHW2n8PUr6BvAiEi2-xHjgd6NwgjFBHQyq8",
    "y": "p5FiE1a9EysW4V56RoBQFoPE1CWE4DS4G2kWKGCBvug",
    "use": "sig",
    "alg": "ES256",
    "kid": "df34552e-721f-4e51-a3d7-4703147f7f5b"
    }
    }
    .
    {
    "callback": "https://toothpic.monokee.com/webhook/?flow_id=2044ea37-2b85-43a6-b04c-1cfce5c2a968",
    "nonce": "17536de5-a723-4ad4-81f2-95653f4364da",
    "azp": "com.toothpic.toothpicmonokee",
    "jti": "7b3996c8-8b09-4979-a8d0-22d25f6ca3da",
    "iat": 1691144600,
    "iss": "https://toothpic.monokee.com",
    "aud": "com.toothpic.toothpicmonokee",
    "exp": 1691145200
    }
    .
    JeH1_L8TkWcd8DuERfrF1f3hh9AjZDe0KVfBVwgLoqLoLB0TN5Za5RFWZzt6qEYz-UO_bIrOY4MaA8Ry1pA1KA
  1. QRCode Display: Monokee initiates an authentication flow by displaying a QRCode containing the challenge. This QRCode serves as an invitation for the end-user to start the authentication process.

    Monokee Generate QRCode
    Figure 3 - Monokee Generate QRCode
    Monokee Show QRCode
    Figure 4 - Monokee Show QRCode
  2. User Interaction: The end-user interacts with Toothpic's app to scan the QRCode and initiate the authentication process. The app generates a cryptographic key, signs the challenge, and sends the signed challenge to Monokee.

  3. Webhook Activation: Monokee's system receives the signed challenge through a webhook. This webhook acts as a communication channel between Toothpic and Monokee, allowing Monokee to process the authentication response.

  4. Challenge Verification: Monokee's webhook verifies the authenticity of the signed challenge. It checks the signature, challenge type (approval or signature), and key information to ensure the integrity of the response.

    Challenge Verification
    Figure 5 - Monokee Challenge verification
  5. Session Unlock: Upon successful verification of the signed challenge, Monokee's webhook unlocks the session that was initially created during the authentication flow. This action grants the end-user access to the desired application or resource, confirming their identity.

Diagram of the implementation

· 20 min read
Sara Meneghetti

Accessing Salesforce through the OpenID Connect protocol

One of the most widely used protocols for implementing federated access is the OpenID Connect protocol. As with SAML, OpenID Connect allows access to an application (Relying Party - RP) by delegating authentication to an external provider (OpenID Provider - OP).

Monokee implements all the dictates of an OpenID Provider, in this regard it has also acquired full certification as OpenID Provider, as can be seen from the official website of the OpenID Fundation at this link.

The following article discusses how to integrate Salesforce and Monokee using the OpenID Connect protocol. Salesforce will play the part of the Relying Party while Monokee will play the part of the OpenID Provider.

From a user experience point of view, a user trying to access a Salesforce custom domain will be redirected to Monokee, which will authenticate him or her and pass to Salesforce the information needed for proper user identification on its side.

How to Configure Monokee as an OpenID Provider

In order to properly configure an OpenID Provider on your Monokee domain, you must comply with the following steps:

  • A Create a custom attribute to save the user's email identifier in Salesforce
  • B Set up an OpenID Provider that has the necessary configurations to properly communicate with Salesforce in the Relying Party role
  • C Add an OpenID application where you can save the Relying Party parameters exposed by Salesforce

A) Attribute containing the user's email on Salesforce

Using the OpenID Connect protocol, by default on Salesforce the user is identified by the email address that he or she uses to log into the custom domain.

It is therefore necessary that all Monokee users for whom you want to enable access to Salesforce using the OpenID Connect protocol, have an attribute valued with the email address they use to log into Salesforce.

It is assumed that an attribute called SalesforceEmail exists for this purpose. Creating and valorizing this field for domain users is outside the scope of this article.

B) OpenID Provider configuration

After having an attribute in which to save the users' email address, we need to create the OpenID Provider to associate with the Monokee domain. To do this, please use the following guidelines.

  1. Navigate to your Monokee custom fully qualified domain name (FQDN) or if you haven't set up a custom FQDN, go to Monokee's default page and enter your domain ID. Then, enter your login credentials to access your account.

  2. Open the left sidebar and select OpenID Providers from the menu.

  3. The page containing any other configurations related to OpenID Providers already registered on the domain will be shown. Click the Add button located in the top right corner to add a new one.

  4. Within the presented modal, in the Core section, enter the desired Name for your new provider, such as Salesforce OpenID Provider. Leave the settings Issuer and JWKS uri unchanged. Then set authorization_code as the value for the field Grant types supported and client_secret_post for the fields Token endpoint authentication methods supported, Revoke endpoint authentication methods supported and Introspect endpoint authentication methods supported.

OpenID Provider Core Configuration
Figure 1 - OpenID Provider Core Configuration
  1. In the sections below the core configuration, enable the value code for Supported response types and plain and S256 for Supported code challenge methods. In the section about Scopes, add the values email and openid.
OpenID Provider Supported response types, Supported code challenge methods and Scopes Configuration
Figure 2 - OpenID Provider Supported response types, Supported code challenge methods and Scopes Configuration
  1. Change tab now and go to the Advanced one. Leave all urls in the Provider endpoints section with the proposed default values.
OpenID Provider Endpoints Configuration
Figure 3 - OpenID Provider Endpoints Configuration
  1. Further down, fill out the form as follows:
    • leave the Claims parameter supported, Request parameter supported and Request_uri parameter supported checks blank
    • set the values query, fragment and form_post for the Supported response modes field
    • set the value public for the Supported subject types field
    • set the value classic for the Supported ACR values field
    • set the value email for the Supported claims field
    • leave Supported languages for the interface field blank
OpendID Connect Provider Advanced Configuration
Figure 4 - OpendID Connect Provider Advanced Configuration
  1. Now go to the "Signature" tab and do the following:
    • choose the value RS256 for the Signature algorithms for the token ID supported field
    • choose the value none for the Signing algorithms for the userinfo object supported field
    • choose the value none for the Signing algorithms for the request supported field
    • click the Add button located inside the Signature card. A dialog will open in which you can generate a public and private key pair.
      • choose from the Select an algorithm for signing select the RS256 algorithm
      • click the Generate Key Pair button, keys will appear in the form
      • click Add in the lower left corner to close the modal related to adding the key pair
OpendID Connect Provider Add Key Pair Configuration
Figure 5 - OpendID Connect Provider Add Key Pair Configuration
OpendID Connect Provider Signature Configuration
Figure 6 - OpendID Connect Provider Signature Configuration
  1. Finally, leave all the configurations in the Encryption tab blank and click the Add button to create the OpenID Connect Provider associated with your custom Monokee domain.
OpendID Connect Provider Encryption Configuration
Figure 7 - OpendID Connect Provider Encryption Configuration

Salesforce configurations

Before proceeding with the creation of the OpenID Connect application, let's do the configuration on the Salesforce side. After this is completed, in fact, the redirect uri, a mandatory value for creating the OpenID Connect application on the Monokee side, will be released by Salesforce.

The following will detail the procedure to be performed on Salesforce to create the Relying Party OpenID Connect that can be integrated with Monokee for single sign-on access.

  1. As a first step, access your Salesforce domain from the Current my Domain Url, which generally has the format https://<my-domain-name>.my.salesforce.com/. You must use a user with an administrative role.
Salesforce Custom Domain login
Figure 8 - Salesforce Custom Domain login
  1. After logging in, navigate to the section of Auth. Providers, which is available at the path Settings > Identity > Auth. Providers.
Salesforce Auth Providers Settings
Figure 9 - Salesforce Auth Providers Settings

2a. In the case that you are using version "Salesforce Classic" instead of "Lightning Experience", you can find this option at the path Administer > Security Controls > Auth. Providers after clicking the Setup button present on the top right of the page.

Salesforce Classic Auth Providers Settings
Figure 10 - Salesforce Classic Auth Providers Settings
  1. From this screen you can create the configuration for the Relying Party OpenID. First, click the "New" button found in the center of the page, this will trigger a redirect to a form where you can enter all the details of the configuration.
Salesforce New Relying Party Settings
Figure 10 - Salesforce New Relying Party Settings
  1. Instructions for properly configuring the Relying Party follow:
    • In the Provider Type select, choose the value Open ID Connect
    • In the Name field, enter the value you want to assign to the configuration, for example, Monokee
    • When the Name field is saved, the URL Suffix field will be automatically valued. Leave the suggested value.
    • The Consumer Key field must contain the client_id value, which is the value that allows the OpenID Provider to identify the Relying Party. This value should then be returned to the configuration of the OpenID application on Monokee. In this example we use the value salesforce_client
    • The Consumer Secret field is the field where to save the client_secret of the Relying Party. This value will also then need to be returned to the configuration of the OpenID Connect application on Monokee. In this example, a random value of ROoD0rFPS75HZE1Ti22D is used.
    • The values for the Authorize Endpoint URL, Token Endpoint URL and User Info Endpoint URL fields can be retrieved from the OpenID Provider configuration done on Monokee earlier. After logging in to your Monokee domain, from the left sidebar, select OpenID Providers and click on the provider created before. The fields can be retrieved from the Advanced section from the Authorization endpoint, Token endpoint and Userinfo endpoint fields, respectively.
      OpendID Connect Provider Advanced Urls
      Figure 11 - OpendID Connect Provider Advanced Urls
    • The value for the Token Issuer field instead can be retrieved from the Core section of the OpenID Provider in Monokee to the Issuer field
      OpendID Connect Provider Issuer Url
      Figure 12 - OpendID Connect Provider Issuer Url
    • As Default Scopes set the value email openid
    • Leave the Send access token in header, Send client credentials in header and Include Consumer Secret in SOAP API Responses checks with the default values
    • Leave fields Custom Error URL and Custom Logout URL blank
    • For the Registration Handler field, you can use a default registration handler. To generate one of them, simply click the Automatically create a registration handler template link
    • As Execute Registration As choose a user who has the necessary permissions to create users, you can do this by clicking on the button with the magnifying glass beside the field and choosing from the proposed profiles
    • You can leave the next Portal, Icon URL and Use Salesforce MFA for this SSO Provider fields with the default values
    • Finally, click the Save button to save the configuration
Salesforce Complete Relying Party Configuration
Figure 13 - Salesforce Complete Relying Party Configuration
  1. Once the configuration is saved, you will be sent back to the configuration detail. The bottom section on Salesforce Configuration will list the urls exposed by Salesforce for integration via OpenID Connect protocol. Of these, let's retrieve the Callback URL value that will later be useful for creating the OpenID Connect application on the Monokee side.
Salesforce Configuration Outcome
Figure 14 - Salesforce Configuration Outcome
  1. The last action to take on Salesforce is to enable login to the custom domain using the OpenID Provider associated with Monokee. To do this you need to navigate to Authentication Configuration menu area located at the Settings > My Domain > Authentication Configuration path if using the "Lightning Experience" version while at the Domain Management > My Domain > Authentication Configuration path if using the "Salesforce Classic" version. Here you need to click the Edit button, which in both cases will open a new page.
Salesforce Authentication Configuration Lightning Experience
Figure 15 - Salesforce Authentication Configuration Lightning Experience
Salesforce Authentication Configuration Classic Version
Figure 16 - Salesforce Authentication Configuration Classic Version

In the opened page Authentication Configuration the available Authentication Services will be displayed. Click the check for the newly added configuration Monokee and then the Save button.

Salesforce Authentication Service Addition
Figure 17 - Salesforce Authentication Service Addition

We can now proceed with the last step to be performed on the Monokee side, which is the creation of the OpenID Connect application in which the Relying Party information exposed by Salesforce will be saved.

C) Create OpenID Connect application on Monokee

Before the OpenID Connect protocol federation can be used to log onto Salesforce, the Monokee-side OpenID Connect application must be created in which to save Salesforce configurations. To do this, follow the steps outlined here:

  1. Navigate to your Monokee custom fully qualified domain name (FQDN) or if you haven't set up a custom FQDN, go to Monokee's default page and enter your domain ID. Then, enter your login credentials to access your account.

  2. Open the left sidebar and select Applications from the menu.

  3. From this page, click the Add button in the upper right corner to create the new application. A modal will open showing the possible types of applications you can add, choose OAuth Application and click Add.

Monokee New Application Type Selection
Figure 18 - Monokee New Application Type Selection
  1. The New Application page will be displayed at the General Configuration section. In this section:
    • Set the Name for the new application, for example Salesforce - OIDC.
    • Optionally, set a Description, in this case we use Salesforce OpenID Connect Integration.
    • Optionally, load an image for your application, it will be displayed in the Application broker. You can do so using the Load From File or Load by URL options.
    • Then click the Next button.
Monokee Application General Information
Figure 19 - Monokee Application General Information
  1. Upon clicking the Next button, you go to the Client Configurations tab. In the first section Client Configurations you need to do the following:
    • Choose the option OpenID
    • Leave the field Require refresh token blank
    • In the select Provider name choose the provider created previously, in this example Salesforce OpenID Provider.
    • The Client ID field must contain the client id specified on Salesforce on the Consumer Key field, in this case salesforce_client
    • The Client Secret field should carry the same value set on Salesforce to Consumer secret, i.e. ROoD0rFPS75HZE1Ti22D
    • As Grant Types choose authorization_code
    • In Token endpoint authentication methods field set client_secret_post value
    • The Redirect URLS field needs to be set to the value retrieved from Salesforce, in this case https://<my-domain-name>.my.salesforce.com/services/authcallback/Monokee
    • In Subject Type field set public as value.
Monokee Application Client Configurations
Figure 20 - Monokee Application Client Configurations
  1. The next section is on Authentication. Here you do the following:
    • Click the Add button in the upper right-hand corner
    • A dialog is opened, on the first entry Authentication Context Class Reference select classic, on the second Authentication flow choose the flow with which you want to protect access to the application, in this case Default Login
    • Click the button Update to confirm your choice, it will close the dialog
    • Finally, choose classic as Default acr
Monokee Application acr Configurations Dialog
Figure 21 - Monokee Application acr Configurations Dialog
Monokee Application acr Configurations
Figure 22 - Monokee Application acr Configurations
  1. Regarding the configuration related to Consent, enable the option Skip the consent screen
Monokee Consent Configurations
Figure 23 - Monokee Consent Configurations
  1. In the Response Types section, enable the code option
Monokee Response Types Configurations
Figure 24 - Monokee Response Types Configurations
  1. Leave the default values for all Duration token/code (seconds) card options
Monokee Duration token scopes Configurations
Figure 25 - Monokee Duration token scopes Configurations
  1. In the Scopes card, set on the Scope field the values openid, email, and offline_access and on the Default Scopes field the values openid and email
Monokee Scopes Configurations
Figure 25 - Monokee Scopes Configurations
  1. Regarding the configuration related to JWT configuration do the following:
    • in field Signature Algorithm for IDToken choose the value RS256. Three more entries will appear, leave fields Encryption Algorithm for IDToken and Content Encryption Algorithm for IDToken empty, and choose the only value available for field Signature Key IDToken
    • in field Signature Algorithm for Userinfo select the value none and do not edit the two values Encryption Algorithm for Userinfo and Content Encryption Algorithm for Userinfo that will have appeared
    • in field Request Signing Algorithm select the value none and leave empty the fields Request Encryption Algorithm and Request Content Encryption Algorithm that have appeared
Monokee JWT Configurations
Figure 26 - Monokee JWT Configurations
  1. Now click the Next button at the bottom left to proceed with the Claims Mapping configurations.

  2. In the Claims mapping card, choose the value email for the fields Scopes used in claims mapping and Claims used in scopes mapping and the value SalesforceEmail for the field Attributes available for mapping.

Monokee Claims Mapping Configurations
Figure 27 - Monokee Claims Mapping Configurations
  1. Valuing the fields in the previous step will cause additional fields to appear, value them as follows.

  2. In the Attribute mapping rule section, perform these steps:

    • click the New Rule button.
      Monokee Attribute Mapping first step
      Figure 28 - Monokee Attribute Mapping first step
    • the New mapping rule modal will be opened, here indicate email in the Value field.
    • click the Add button.
      Monokee Attribute Mapping second step
      Figure 29 - Monokee Attribute Mapping second step
    • the Choose value modal will be opened, here choose the value SalesforceEmail for the Value field
    • click Add button again
      Monokee Attribute Mapping third step
      Figure 30 - Monokee Attribute Mapping third step
    • the modal is closed and a summary of the configuration for the attribute mapping is shown
      Monokee Attribute Mapping result
      Figure 31 - Monokee Attribute Mapping result
  3. In the claim section:

    • click the Add button
      Monokee Claim Configuration first step
      Figure 32 - Monokee Claim Configuration first step
    • the Add new claim modal will be opened. Here choose email as the value of both the Scope field and the Associated claim field and click add
      Monokee Claim Configuration second step
      Figure 33 - Monokee Claim Configuration second step
    • the modal will be closed and a summary of the configuration for the claims will be shown
      Monokee Claim Configuration summary
      Figure 34 - Monokee Claim Configuration summary
  4. In the last section Claim location, enable the claim email for both ID_TOKEN and USERINFO.

    Monokee Claim Location Configuration
    Figure 35 - Monokee Claim Location Configuration
  5. Click the bottom right corner Create button to create the application.

The application was created and configured so that proper communication can take place between Monokee and Salesforce according to the requirements of the OpenID Connect protocol. It is now possible to associate the application with users and groups of interest in order to allow them to access Salesforce through Monokee.

How to test access to Salesforce

In order to test access to the application, it is necessary that the application created in the previous paragraph has been assigned to the relevant users or groups and that the users have the custom attribute SalesforceEmail valued with the email address with which they are censored on Salesforce.

Once these preliminary steps have been taken, access can be tested directly from the Salesforce login page at the url https://<my-domain-name>.my.salesforce.com/.

The page will show the classic login form and the Login with Monokee button.

Salesforce OpenID Connect login
Figure 36 - Salesforce OpenID Connect login

By clicking this button, you will be redirected to the login page of the flow associated with the classic acr, as per the configuration made earlier, and, when the login process is complete, you will be redirected to the Salesforce custom domain home page.

If you want to leave only federated access via Monokee enabled, you will simply go back to the Authentication Configuration page on Salesforce and disable access via Login Form by unchecking the relevant item and clicking Save.

Salesforce disable Login Form
Figure 37 - Salesforce disable Login Form

By doing this, the Salesforce custom domain login page will automatically redirect to Monokee for login without showing the classic login form.

· 13 min read
Alexandru Botea

How to use SAML 2.0 protocol to access Secret Server

Secret Server allows the use of SAML Identity Provider (IDP) authentication instead of the normal authentication process for single sign-on (SSO). To do this, SS acts as a SAML Service Provider (SP) and communicates with Monokee that's acting as a SAML IDP.

In this use case, the user who wants to access Secret Server will not log in through a Secret Server form, but will be redirected to Monokee, which will take care of validating the credentials and communicating the data necessary for user identification to Secret Server, which will eventually log the user in.

Then, the former authenticates the user and provides the latter with the attributes necessary for it to be correctly identified and for it to access the service.

In the following article we explain how the proposed scenario can be put in place; therefore, the steps to be taken on the Secret Server side and the Monokee side in order to achieve a proper SAML 2.0 configuration related to the two providers will be explained.

Monokee Configurations

In order to get Monokee's domain and Secret Server's domain to communicate properly, you need to do three things on Monokee:

  • A Add a custom attribute where the user's identifier will be present on Secret Server
  • B Set up a SAML 2.0 identity provider that has the correct parameters to successfully work with Secret Server
  • C Configure a SAML 2.0 application with all the parameters related to Secret Server.

The first two points will be explained below, while the third will be discussed in more detail after the necessary Secret Server-side operations are explained.

A) Attribute to Identify the User on Secret Server

Secret Server allows the user to be identified only by username which is uniquely within the custom domain.

It is therefore necessary for the Monokee side to have a custom attribute in which this field is saved for each user in the domain.

It is assumed that an attribute called secretserver_user exists for this purpose. Creating and enhancing this field for domain users is outside the scope of this article.

B) Setting up the Identity Provider on the Monokee side

The next stage is to configure the Identity Provider, let's see what steps are required to accomplish this.

  1. Navigate to your Monokee custom fully qualified domain name (FQDN) or if you haven't set up a custom FQDN, go to Monokee's default page and enter your domain ID. Then, enter your login credentials to access your account.

  2. Open the left sidebar and select SAML Providers from the menu.

  3. This will display a two-tab page, choose the IDENTITY PROVIDERS tab. Click the Add button located in the top right corner.

  4. Within the presented modal, in the General configuration section, enter the desired Name for your new provider, such as Secret Server IDP SAML 2.0. Leave all other settings unchanged.

IDP General Configuration
Figure 1 - IDP General Configuration
  1. For this use case, it is not necessary to specify values for Organization and Contact person, so you can leave the fields of the two reference sections empty.

  2. Secret Server supports sending signed SAML Requests, so the flag IDP requires signed authentication requests in Signing options section can be checked.

IDP Signing options
Figure 2 - IDP Signing options
  1. Load your PKCS1 Private Key and the corresponding Certificate in the Signature section. If you want you can generate this key-pair with the following openssl command:

    openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048

    A series of information will be asked, here's an example:

    • Country Name: IT
    • State or Province Name: TN
    • Locality Name: Trento
    • Organization Name: Monokee
    • Organizational Unit Name: Monokee SAML 2.0
    • Common Name: 1f414952-d73b-4c79-a3cb-fb5d413fe5fe
    • Email Address: john.doe@example.org

    caution

    For the Common Name you can use the value of <provider_id> generated by the Entity ID.

    IDP General Configuration EntityID

    This command should output a certificate directly in the terminal and the private key will be placed in a file named privkey.pem. The private key will be in PKCS8 format so it must be converted to PKCS1 with the following command:

    openssl pkey -in privkey.pem -traditional

    The new private key will be displayed in the terminal output.

    Certificate Creation Output
    Figure 3 - Certificate Creation Output
  2. Left untouched the Single Sign-On Services and Single Logout services configurations.

IDP SSO and SLO Services
Figure 4 - IDP Single Sign-On Services and Single Logout services
  1. The Attributes section can be left empty, as Secret Server does not require any additional attributes other than the subject.
IDP Attributes Exposed
Figure 5 - IDP Attributes Exposed
  1. Click the Save button to save the configuration.

  2. Now click the button representing a cloud with a downward arrow to download the identity provider metadata file you just created. Upon clicking the button a modal will be opened, so download the file by pressing the Download button without flagging the Request signed metadata checkbox. The file you just downloaded will be needed for Secret Server side configurations.

IDP Metadata Download Icon
Figure 6 - IDP Metadata Download Icon
IDP Metadata Download Dialog
Figure 7 - IDP Metadata Download Dialog

Secret Server Configurations

Let's leave aside for a moment the configuration of the SAML 2.0 application on Monokee to complete the part about defining the service provider on the Secret Server side. These informations will then be necessary for the creation of the application on Monokee.

Below is the procedure for importing the SAML 2.0 identity provider details just defined on Monokee to Secret Server and for downloading the SAML 2.0 service provider metadata that is associated with Secret Server.

  1. As a first step, access your Secret Server domain. You must use a user with an administrative role.
Secret Server login
Figure 8 - Secret Server login
  1. Once logged in, go to the Single Sign-On Settings section, which can be found in the left menu at the Administration > Core Actions > Configuration > SAML. Click on the edit button and check the checkbox of the SAML Enabled option to enable it. Click the Save button.
Secret Server Enable Single Sign-On
Figure 9 - Secret Server Enable Single Sign-On
  1. From this screen you can also upload the identity provider configuration previously created on Monokee. Under IDENTITY PROVIDERS section click on Create New Identity Provider. A popup will be displayed with 2 options. Click on the second option which is Import IDP from XML Metadata. Select the file idp_metadata_Secret Server IDP SAML 2.0.xml exported previusly from Monokee.
Secret Server Create New Identity Provider
Figure 10 - Secret Server Create New Identity Provider
Secret Server Import IDP Metadata File
Figure 11 - Secret Server Import IDP Metadata File
  1. After the successful upload, you will note the Identity Provider is added under this section (You can change the DISPLAY NAME as you like, it will be displayed later on the LOGIN PAGE).
Sercret Server Identity Provider Added
Figure 12 - Sercret Server Identity Provider Added
  1. Now that the Identity provider has been added, it is possible to download the service provider metadata related to the Monokee configuration. This file will be useful for creating the SAML application on Monokee. Before doing that you need to set a Name that must be identical to the Entity Identifier field in Monokee App by clicking on the Edit button. As an example we choose the SecretServer SP name. A SSL certificate of the Secret Server Public FQDN must be also added by clicking on the "Select certificate" link, in our example it was generated by Let's Encrypt. Click on the Download Service Provider Metadata (XML) button.
Secret Server Provider Settings
Figure 13 - Secret Server Provider Settings

We now have all the necessary data to proceed with the creation of the SAML application on Monokee.

C) Create SAML 2.0 Application on the Monokee side

The last configuration to do before you can test Secret Server access via SAML 2.0 protocol is to create a SAML Application on Monokee by following the procedure below:

  1. Navigate to your Monokee custom fully qualified domain name (FQDN) or if you haven't set up a custom FQDN, go to Monokee's default page and enter your domain ID. Then, enter your login credentials to access your account.

  2. Open the left sidebar and select Applications from the menu.

  3. This will display a list of applications. To create the application, click the Add button located in the top right corner of the table. Then, select SAML Application and click Add.

Add SAML 2.0 Application
Figure 14 - Add SAML 2.0 Application
  1. Monokee will open the General Configuration step.

  2. Set the Name of you application. For example Secret Server.

  3. Leave the URL parameter empty.

  4. Optionally, set a Description for your application, for example Secret Server SAML 2.0 integration.

  5. Leave the Hide this application from the application broker parameter unchecked, this will allow you to see the application in Monokee Application Broker.

  6. You can load an optional application icon using the Load From File or Load by URL options.

  7. Skip the Protect with flow configuration. In this way the default Authentication Flow will protect this app.

  8. Click Create to proceed to the SAML 2.0 specific configuration. You will be referred to the Service Provider Configuration step.

General Application Configuration
Figure 15 - General Application Configuration
  1. In the Service Provider metadata section you can load the Secret Server metadata previously downloaded. You can load it directly from Load from file input. This operation will automatically fill all the fields on this step.
Load Metadata from File
Figure 16 - Load Metadata from File
  1. Check the SP signs authentication requests and SP requires signed assertions options and add the public certificate of your public FQDN that you have generated in the previus step "Secret Server Configurations - 5".

    Signing Options And Signature
    Figure 17 - Signing Options And Signature
  2. Click Next to proceed to the Additional Configuration step.

  3. In the Additional Configuration section, in the Identity Provider input select, choose the identity provider created before Secret Server IDP SAML 2.0, in Signature algorithm choose the value http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 and in Digest algorithm the value http://www.w3.org/2001/04/xmlenc#sha256.

  4. All the fields in Identity provider signing options can be checked.

IDP App Configuration
Figure 18 - IDP App Configuration
  1. Click Next to proceed to the last step Response Statement Configuration.

  2. In the Authentication statement options select urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress as Subject format and urn:oasis:names:tc:SAML:2.0:cm:bearer as Subject confirmation method.

Subject Format and Confirmation Method
Figure 19 - Subject Format and Confirmation Method
  1. In the Subject mapping rule you must specify the attribute to be mapped with the subject. To do so, follow the steps:
    • Click the pencil icon next to subject label
    • Click the Add button, a dialog will appear
    • In the Value select present in the dialog choose the attribute secretserver_user
    • Click the Add button in the dialog
Subject Rule Configuration
Figure 20 - Subject Rule Configuration
  1. You can left the Attribute statement section empty.

  2. Click the bottom right corner Create button to save the configuration.

You can now associate the newly created application with the users and groups for which you need to grant access to the application.

Time to test the configuration

It is now time to test the configuration made.

As a first step, we need to value the secretserver_user attribute for all users who are to have access to the application. For testing purposes, you can first do this with your own user. The value of the attribute must match the username of one of the users in the Secret Server domain that you have federated.

We are going to test the configuration in both the IDP initiated and SP initiated scenarios.

IDP Initiated SSO

In the IDP initiated scenario, the login flow starts from the Identity Provider, so in this case from Monokee. Then go to your application broker and click on the card for the Secret Server application you just created.

Secret Server IDP Initiated login
Figure 21 - Secret Server IDP Initiated login

The click will cause a new browser tab to open where the SAML 2.0 IDP Initiated login flow will be initiated, after which you will be redirected to the home page of the configured Secret Server domain.

SP Initiated SSO

On the other hand, to test the SP initiated flow you must go to the login page of your Secret Server domain, at the url https://<my-domain-name>/secretserver.

Secret Server SP Initiated login
Figure 22 - Secret Server SP Initiated login

By clicking on the Demo Monokee SAML link will start the SP initiated login flow which will first authenticate the user according to the chosen security flow and then send back to the home page of the configured secret server domain.

Monokee Login
Figure 23 - Monokee Login

· 6 min read
Enrico Fabris
Sara Meneghetti
Valentina Codogno

Monokee Launches Version 3.0.0: More Powerful Than Ever Before

Monokee, the leading identity and access management solution, has just launched version 3.0.0 of its powerful security platform. This latest version of Monokee brings a wide range of new features and improvements, making it more powerful and comprehensive than ever before.

One of the standout features of Monokee 3.0.0 is the Visual Identity Orchestrator, which has been significantly enhanced to provide even greater flexibility and control for managing identity and access within organizations. Here are some of the benefits of the new and improved Visual Identity Orchestrator:

  • Enhanced Customization: with the improved Visual Identity Orchestrator, organizations can now customize and manage their identity and access workflows with greater ease and precision, saving valuable time and resources.
  • Increased Governance Capabilities: the latest iteration of Monokee introduces enhanced governance functionalities. Thanks to the Visual Identity Orchestrator, organizations can now efficiently manage the entire user lifecycle.
  • Improved Security: review of encryption systems and improvement through the use of more robust algorithms.
  • Improved User Experience: the user interface of the Visual Identity Orchestrator has been streamlined and optimized to provide a more intuitive and user-friendly experience.

In particular, the new category Webhook flows has been added such flows are exclusively backend-side, meaning that all flow execution is performed server-side and no user interaction is involved. This type of flow allows, for example, domain administrators to create flows that trigger server-side operations callable from schedulable crons to synchronize data.

Moreover, in Admin flows, besides the Invite User category already present, the following have been added:

  • Delete User: with these flows, the domain administrator can customize the process of deleting a user from domain.
  • Lock User: users for whom this flow will be run will be blocked and temporarily unable to login to the domain anymore.
  • Unlock User: the users locked can be re-enable to login with these flows.

In conclusion, these are the nodes that have been added to flows:

  • Monokee - User Pending: to check whether a user has already accepted the domain invitation or not.
  • Monokee - User Locked: to check if a user is blocked or not.
  • Monokee - Lock User: to block access to the domain by a user.
  • Monokee - Unlock User: to unblock access to the domain by a user.
  • Monokee - Check User Roles: to check if a user has a role or not.
  • Monokee - Check User Groups Association: to check if a user belongs to a specific group or not.
  • Monokee - Update User Password: to update user's Monokee password.
  • Monokee - Manage User Application: to associate or remove applications to the user.
  • OpenID - Azure: to delegate login to Azure OpenID provider.
  • OpenID - Generic Implicit flow: to delegate login with OpenID Implicit flow.
  • Hash values: to hash a value.
  • Array Operations: to concat two different arrays.
  • Loop: to iterate over the elements of an array.
  • JSON Parse: to parse a string in JSON.
  • JSON Stringify: to parse a JSON in string.
  • URL Encode: to URL encode a string.
  • URL Decode: to URL decode a string.
  • Base64 Encode: to encode a string in Base64 format.
  • Base64 Decode: to decode a Base64 format string.
  • Flow session - Update variables: to apply functions to variables already in flow session.

In addition to the enhanced Visual Identity Orchestrator, Monokee 3.0.0 also includes a range of other new features and improvements, such as:

  • User can be locked/unlocked:

    The user menu was enhanced with new user lock/unlock functionalities. These two new actions on the user are the result of the execution of the relative administrative block/unblock flows that have previously been configured by a domain administrator. This makes it possible to execute different lock/unlock flows depending on the user to be acted upon. Furthermore, this allows the domain administrator to be able to customize this process as desired.

  • Review of SAML 2.0 applications configuration:

    The process of adding/updating a SAML 2.0 application has been completely revised. Specifically, the steps that guide the user have been made more user friendly and reorganized as follows:

    • step 1: General configuration, with the addition of choosing the login flow that protects the application.
    • step 2: Service Provider configuration, where it is possible to upload the Service Provider metadata or alternatively fill in the metadata data only fields by hand.
    • step 3: Additional configuration, where it is possible to choose one the SAML 2.0 Identity Provider defined in the domain and its related signature configurations.
    • step 4: Response statement configuration, in this section it is possible configure the parameters for generating Authentication statement and Attribute statement.

Together, these improvements make Monokee even more effective at protecting against security threats and ensuring compliance with regulatory requirements.

"We're thrilled to be launching version 3.0.0 of Monokee, this latest version is the result of our continued commitment to providing our customers with the most powerful and comprehensive identity and access management solutions on the market."

Roberto Griggio, CEO at Monokee

Monokee version 3.0.0 is available now. To learn more about how it can help your organization better protect its critical assets, visit monokee website and monokee documentation.

About Monokee:

Monokee is a leading identity and access management solution, helping organizations of all sizes protect their critical assets and ensure compliance with regulatory requirements. With a focus on innovation and customer satisfaction, Monokee is dedicated to providing the most comprehensive and powerful security solution on the market.

Release Notes

  • Webhook Flows
  • Admin Flows:
    • Delete User
    • Lock User
    • Unlock User
  • Flow nodes:
    • Monokee - User Pending
    • Monokee - User Locked
    • Monokee - Lock User
    • Monokee - Unlock User
    • Monokee - Check User Roles
    • Monokee - Check User Groups Association
    • Monokee - Update User Password
    • Monokee - Manage User Application
    • OpenID - Azure
    • OpenID - Generic Implicit flow
    • Hash values
    • Array Operations
    • Loop
    • JSON Parse
    • JSON Stringify
    • URL Encode
    • URL Decode
    • Base64 Encode
    • Base64 Decode
    • Flow session - Update variables
  • User Menu Review
  • Application SAML 2.0 Configuration review

· 15 min read
Sara Meneghetti

How to use SAML 2.0 protocol to access Salesforce

An effective way to gain access to a custom Salesforce domain by delegating credential control to Monokee is attaché to the saml 2.0 federation protocol.

In this use case, the user who wants to access Salesforce will not log in through a Salesforce form, but will be redirected to Monokee, which will take care of validating the credentials and communicating the data necessary for user identification to Salesforce, which will eventually log the user in.

The requirement illustrated above describes the context in which Monokee acts as an Identity Provider SAML 2.0, while Salesforce acts as a Service Provider SAML 2.0. Then, the former authenticates the user and provides the latter with the attributes necessary for it to be correctly identified and for it to access the service.

In the following article we explain how the proposed scenario can be put in place; therefore, the steps to be taken on the Salesforce side and the Monokee side in order to achieve a proper SAML 2.0 configuration related to the two providers will be explained.

Monokee Configurations

In order to get Monokee's domain and Salesforce's domain to communicate properly, you need to do three things on Monokee:

  • A Add a custom attribute where the user's identifier will be present on Salesforce
  • B Set up a SAML 2.0 identity provider that has the correct parameters to successfully work with Salesforce
  • C Configure a SAML 2.0 application with all the parameters related to Salesforce.

The first two points will be explained below, while the third will be discussed in more detail after the necessary Salesforce-side operations are explained.

A) Attribute to Identify the User on Salesforce

Salesforce allows the user to be identified in two different ways: using the email address used for login or with another attribute that allows the user to be uniquely identified within the custom domain.

In the article, the first case is explored, thus the use of the email address that the user enters when logging in.

It is therefore necessary for the Monokee side to have a custom attribute in which this field is saved for each user in the domain.

It is assumed that an attribute called SalesforceEmail exists for this purpose. Creating and valorizing this field for domain users is outside the scope of this article.

B) Setting up the Identity Provider on the Monokee side

The next stage is to configure the Identity Provider, let's see what steps are required to accomplish this.

  1. Navigate to your Monokee custom fully qualified domain name (FQDN) or if you haven't set up a custom FQDN, go to Monokee's default page and enter your domain ID. Then, enter your login credentials to access your account.

  2. Open the left sidebar and select SAML Providers from the menu.

  3. This will display a two-tab page, choose the IDENTITY PROVIDERS tab. Click the Add button located in the top right corner.

  4. Within the presented modal, in the General configuration section, enter the desired Name for your new provider, such as Salesforce IDP SAML 2.0. Leave all other settings unchanged.

IDP General Configuration
Figure 1 - IDP General Configuration
  1. For this use case, it is not necessary to specify values for Organization and Contact person, so you can leave the fields of the two reference sections empty.

  2. Salesforce supports sending signed Saml Requests, so the flag IDP requires signed authentication requests in Signing options section can be checked.

IDP Signing options
Figure 2 - IDP Signing options
  1. Load your PKCS1 Private Key and the corresponding Certificate in the Signature section. If you want you can generate this key-pair with the following openssl command:

    openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048

    A series of information will be asked, here's an example:

    • Country Name: IT
    • State or Province Name: TN
    • Locality Name: Trento
    • Organization Name: Monokee
    • Organizational Unit Name: Monokee SAML 2.0
    • Common Name: 1f414952-d73b-4c79-a3cb-fb5d413fe5fe
    • Email Address: john.doe@example.org

    caution

    For the Common Name you can use the <provider_id> generated by the EntityID

    IDP General Configuration EntityID

    This command should output a certificate directly in the terminal and the private key will be placed in a file named privkey.pem. The private key will be in PKCS8 format so it must be converted to PKCS1 with the following command:

    openssl pkey -in privkey.pem -traditional

    The new private key will be displayed in the terminal output.

    Certificate Creation Output
    Figure 3 - Certificate Creation Output
  2. Left untouched the Single Sign-On Services and Single Logout services configurations.

IDP SSO and SLO Services
Figure 4 - IDP Single Sign-On Services and Single Logout services
  1. The Attributes section can be left empty, as Salesforce does not require any additional attributes other than the subject.
IDP Attributes Exposed
Figure 5 - IDP Attributes Exposed
  1. Click the bottom right Save button to save the configuration.

  2. Now click the button representing a cloud with a downward arrow to download the identity provider metadata file you just created. Upon clicking the button a modal will be opened, so download the file by pressing the Download button without flagging the Request signed metadata checkbox. The file you just downloaded will be needed for Salesforce side configurations.

IDP Metadata Download Icon
Figure 6 - IDP Metadata Download Icon
IDP Metadata Download Dialog
Figure 7 - IDP Metadata Download Dialog

Salesforce Configurations

Let's leave aside for a moment the configuration of the SAML 2.0 application on Monokee to complete the part about defining the service provider on the Salesforce side. These information will then be necessary for the creation of the application on Monokee.

Below is the procedure for importing the SAML 2.0 identity provider details just defined on Monokee to Salesforce and for downloading the SAML 2.0 service provider metadata that is associated with Salesforce.

  1. As a first step, access your Salesforce domain from the Current my Domain Url, which generally has the format https://<my-domain-name>.my.salesforce.com/. You must use a user with an administrative role.
Salesforce Custom Domain login
Figure 8 - Salesforce Custom Domain login
  1. Once logged in, go to the Single Sign-On Settings section, which can be found in the left menu at the Settings > Identity > Single Sign-On Settings path.
Salesforce Single Sign-On Settings
Figure 9 - Salesforce Single Sign-On Settings

2a. If you are using the "Salesforce Classic" version instead of the "Lightning Experience" one, you can find the same entry by clicking on the Setup button in the upper right-hand corner and, from the left-hand menu that will have appeared, to the Administer > Security Controls > Single Sign-On Settings path.

Salesforce Classic Single Sign-On Settings
Figure 10 - Salesforce Classic Single Sign-On Settings
  1. From this screen you can upload the identity provider configuration previously created on Monokee. It is recommended to do so through the New from Metadata File button, uploading the metadata file downloaded as explained above.
Salesforce Import IDP Metadata File
Figure 11 - Salesforce Import IDP Metadata File
  1. After uploading the file as explained in the Salesforce form, click the Create button. You will be redirected to the configuration import summary page, here you need to give a Name and API Name for the configuration, e.g. Monokee, then click the Save button at the bottom to confirm the import.
Salesforce Import IDP Summary
Figure 12 - Salesforce Import IDP Summary
  1. Therefore, from the final summary pages, it is possible to download the service provider metadata related to the Salesforce configuration from the Download Metadata button. This file will be useful for creating the SAML application on Monokee.
Salesforce Download SP Metadata
Figure 13 - Salesforce Download SP Metadata
  1. Finally, you need to enable the identity provider you just uploaded for it to show up in the Salesforce domain login form. This will allow the user to choose from the login page whether to log in with the default form or to delegate the login to Monokee. To do this you need to access the Authentication Configuration menu area located at the Settings > My Domain > Authentication Configuration path if using the "Lightning Experience" version while at the Domain Management > My Domain > Authentication Configuration path if using the "Salesforce Classic" version. Here you need to click the Edit button, which in both cases will open a new page.
Salesforce Authentication Configuration Lightning Experience
Figure 14 - Salesforce Authentication Configuration Lightning Experience
Salesforce Authentication Configuration Classic Version
Figure 15 - Salesforce Authentication Configuration Classic Version

In the opened page Authentication Configuration the available Authentication Services will be displayed. Click the check for the newly added configuration Monokee and then the Save button.

Salesforce Authentication Service Addition
Figure 16 - Salesforce Authentication Service Addition

We now have all the necessary data to proceed with the creation of the SAML application on Monokee.

C) Create SAML 2.0 Application on the Monokee side

The last configuration to do before you can test Salesforce access via SAML 2.0 protocol is to create a saml application on Monokee. Following is the procedure to be performed:

  1. Navigate to your Monokee custom fully qualified domain name (FQDN) or if you haven't set up a custom FQDN, go to Monokee's default page and enter your domain ID. Then, enter your login credentials to access your account.

  2. Open the left sidebar and select Applications from the menu.

  3. This will display a list of applications. To create the application, click the Add button located in the top right corner of the table. Then, select SAML Application and click Add.

Add SAML 2.0 Application
Figure 17 - Add SAML 2.0 Application
  1. Monokee will open the General Configuration step.

  2. Set the Name of you application. For example Salesforce.

  3. Leave the URL parameter empty.

  4. Optionally, set a Description for your application, for example Salesforce SAML 2.0 integration.

  5. Leave the Hide this application from the application broker parameter unchecked, this will allow you to see the application in Monokee Application Broker.

  6. You can load an optional application icon using the Load From File or Load by URL options.

  7. Skip the Protect with flow configuration. In this way the default Authentication Flow will protect this app.

  8. Click Create to proceed to the SAML 2.0 specific configuration. You will be referred to the Service Provider Configuration step.

General Application Configuration
Figure 18 - General Application Configuration
  1. In the Service Provider metadata section you can load the Salesforce metadata previously downloaded. You can load it directly from Load from file input. This operation will automatically fill all the fields on this step.
Load Metadata from File
Figure 19 - Load Metadata from File
  1. Click Next to proceed to the Additional Configuration step.

  2. In the Additional Configuration section, in the Identity Provider select choose the identity provider created before Salesforce IDP SAML 2.0, in Signature algorithm choose the value http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 and in Digest algorithm the value http://www.w3.org/2001/04/xmlenc#sha256.

  3. All the fields in Identity provider signing options can be checked.

IDP App Configuration
Figure 20 - IDP App Configuration
  1. Click Next to proceed to the last step Response Statement Configuration.

  2. In the Authentication statement options select urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified as Subject format and urn:oasis:names:tc:SAML:2.0:cm:bearer as Subject confirmation method.

Subject Format and Confirmation Method
Figure 21 - Subject Format and Confirmation Method
  1. In the Subject mapping rule you must specify the attribute to be mapped with the subject. To do so, follow the steps:
    • Click the pencil icon next to subject label
    • Click the Add button, a dialog will appear
    • In the Value select present in the dialog choose the attribute SalesforceEmail
    • Click the Add button in the dialog
Subject Rule Configuration
Figure 22 - Subject Rule Configuration
  1. You can left the Attribute statement section empty.

  2. Click the bottom right corner Create button to save the configuration.

You can now associate the newly created application with the users and groups for which you need to grant access to the application.

Time to test the configuration

It is now time to test the configuration made.

As a first step, we need to value the SalesforceEmail attribute for all users who are to have access to the application. For testing purposes, you can first do this with your own user. The value of the attribute must match the email of one of the users in the Salesforce domain that you have federated.

We are going to test the configuration in both the IDP initiated and SP initiated scenarios.

IDP Initiated SSO

In the IDP initiated scenario, the login flow starts from the Identity Provider, so in this case from Monokee. Then go to your application broker and click on the card for the Salesforce application you just created.

Salesforce IDP Initiated login
Figure 23 - Salesforce IDP Initiated login

The click will cause a new browser tab to open where the SAML 2.0 IDP Initiated login flow will be initiated, after which you will be redirected to the home page of the configured Salesforce domain.

SP Initiated SSO

On the other hand, to test the sp initiated flow you must go to the login page of your Salesforce domain, at the url https://<my-domain-name>.my.salesforce.com/. Here, in addition to the classic domain login form, a button should have appeared asking if you want to log in through Monokee.

Salesforce SP Initiated login
Figure 24 - Salesforce SP Initiated login

Clicking on this button will start the SP initiated login flow which will first authenticate the user according to the chosen security flow and then send back to the home page of the configured salesforce domain.

If you want to log in to the Salesforce custom domain using only Monokee via Saml protocol, you can do so by navigating to the Authentication Configuration page on Salesforce and disable access via Login Form by unchecking the relevant item and clicking Save.

Salesforce disable Login Form
Figure 25 - Salesforce disable Login Form

By so doing, the Salesforce custom domain login page will automatically redirect to Monokee for login without displaying the classic login form.

· 12 min read
Sara Meneghetti

Accessing Microsoft 365 with Monokee: possible with SAML 2.0 protocol

Accessing a Microsoft 365 tenant using Monokee is possible using the SAML 2.0 protocol. In this scenario Monokee will act as an Identity Provider (IDP) delivering identities to Microsoft 365 which will then act as a Service Provider (SP).

Specifically, this means that when a user of this Microsoft 365 tenant tries to log in to Microsoft 365, he will be redirected to the login page of the Monokee domain, which will authenticate the user and finally return to Microsoft 365 the user's information required for authentication on his side according to the dictates of the SAML 2.0 protocol.

This article explains how to integrate Microsoft 365 as a SAML 2.0 application in Monokee, starting with the configurations to be made on the Monokee, continuing with Office 365 side configurations and ending with the creation of the SAML application on the Monokee side.

Preliminary steps on the Monokee side

In order to be able to federate between a Microsoft 365 tenant and a Monokee domain, it is necessary to do some preliminary work on the Monokee side.

In particular, it is necessary for the Monokee domain, and thus the users in it, to have the required attributes that Microsoft will use to identify the user who wishes to log in, and to create the identity provider configuration of the Monokee domain.

User identification attributes for Microsoft 365

In order to identify the user, Microsoft needs the user's immutableID and email address from Azure.

We therefore assume that two custom attributes exist on the Monokee domain that contain this information, called AzureImmutableID and AzureIDPEmail respectively.

The first attribute AzureImmutableID will be sent as the subject in the authentication SAML Response, while AzureIDPEmail will be used to value an attribute to be included in the attribute statement of the response.

Creating these custom attributes and valuing them for domain users is outside the scope of this article.

Creation of the SAML 2.0 Identity Provider

We can proceed with the creation of an Identity Provider SAML 2.0 on the Monokee domain.

Below are the steps to follow with the specialized procedure for Microsoft 365.

  1. Navigate to your Monokee custom fully qualified domain name (FQDN) or if you haven't set up a custom FQDN, go to Monokee's default page and enter your domain ID. Then, enter your login credentials to access your account.

  2. Open the left sidebar and select SAML Providers from the menu.

  3. This will display a two-tab page, choose the IDENTITY PROVIDERS tab. Click the Add button located in the top right corner.

  4. Within the presented modal, in the General configuration section, enter the desired Name for your new provider, such as Microsoft 365 IDP SAML 2.0. Leave all other settings unchanged.

IDP General Configuration
Figure 1 - IDP General Configuration
  1. For this use case, it is not necessary to specify values for Organization and Contact person, so you can leave the fields of the two reference sections empty.

  2. Microsoft 365 does not send signed Saml Requests, so the flag IDP requires signed authentication requests in Signing options section must remain unchecked by default.

IDP Signing options
Figure 2 - IDP Signing options
  1. Load your PKCS1 Private Key and the corresponding Certificate in the Signature section. If you want you can generate this key-pair with the following openssl command:

    openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048

    A series of information will be asked, here's an example:

    • Country Name: IT
    • State or Province Name: TN
    • Locality Name: Trento
    • Organization Name: Monokee
    • Organizational Unit Name: Monokee SAML 2.0
    • Common Name: 1f414952-d73b-4c79-a3cb-fb5d413fe5fe
    • Email Address: john.doe@example.org

    caution

    For the Common Name you can use the <provider_id> generated by the EntityID

    IDP General Configuration EntityID

    This command should output a certificate directly in the terminal and the private key will be placed in a file named privkey.pem. The private key will be in PKCS8 format so it must be converted to PKCS1 with the following command:

    openssl pkey -in privkey.pem -traditional

    The new private key will be displayed in the terminal output.

Certificate Creation Output
Figure 3 - Certificate Creation Output
  1. Left untouched the Single Sign-On Services and Single Logout services configurations.
IDP SSO and SLO Services
Figure 4 - IDP Single Sign-On Services and Single Logout services
  1. In the Attributes section, include the attribute IDPEmail which is the only attribute required by Microsoft 365 in addition to the subject for user authentication with SAML 2.0 protocol. To do so, follow these steps:

    • Click on the Add button on the Attributes section, a dialogue will appear
    • In the dialog, set IDPEmail as the value for both the Name and Descriptive Name fields
    • Click the Add button of the dialogue to confirm the operation
IDP Attributes Exposed
Figure 5 - IDP Attributes Exposed
  1. Click the bottom right Save button to save the configuration.

How to federate an Microsoft 365 tenant with Monokee

After completing the preliminary steps on the Monokee side, it is necessary to continue the configuration on Microsoft 365 so that it recognizes Monokee as an external Identity Provider.

Configuration must be done using the Microsoft Azure Active Directory Module for Windows PowerShell.

Once the application is open, you will need to log in with an administrative user using the commands:

$UserCredential = Get-Credential
Connect-MsolService -Credential $UserCredential

The former will show a pop-up asking you to enter credentials, while the latter will take care of the actual connection.

You can for convenience save the domain name in a variable through:

$dom=<microsoft365-tenant-hostname>

where microsoft365-tenant-hostname is the hostname of your Microsoft 365 tenant.

Once connected, to view the current configuration you need to type the command:

Get-MsolDomainFederationSettings

You will then be prompted for the domain name, and once indicated, the current configuration will be displayed.

To change the configuration, it is first necessary to put the domain in Managed mode by typing:

Set-MsolDomainAuthentication -DomainName $dom -Authentication Managed

Now we need to indicate the new configuration parameters, saved on variables:

$entityid=<monokee-idp-entity-id>
$ssourl=<monokee-idp-single-sign-on-services>
$slourl=<monokee-idp-single-logout-services>
$cert=<monokee-idp-signing-certificate>

where the specified fields should be replaced as follows:

  • monokee-idp-entity-id is the entity ID of the Identity Provider SAML 2.0 created before, you can find this value in the Identity Provider configuration at the field Entity ID.
  • monokee-idp-single-sign-on-services is the location of the Single Sign-On service of the Identity Provider. You can find the correct value on the Identity Provider configuration page, within the Single Sign-On Services section by clicking the down arrow icon next to the urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST string and by copying the value at field Location.
  • monokee-idp-single-logout-services is the location of the Single Logout service of the Identity Provider. You can find the correct value on the Identity Provider configuration page, within the Single logout services section by clicking the down arrow icon next to the urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST string and by copying the value at field Location.
  • monokee-idp-signing-certificate is the certificate used by the Identity Provider to sign the responses to be sent to the Service Provider. You can find the correct value on the Identity Provider configuration page, within the Signature section by clicking the down arrow of the card and by copying the value at field Certificate.

You can now set these new values using the command:

Set-MsolDomainAuthentication -DomainName $dom -FederationBrandName $dom -Authentication Federated -PassiveLogOnUri $ssourl -SigningCertificate $cert -IssuerUri $entityid -LogOffUri $slourl -PreferredAuthenticationProtocol SAMLP

At this point you can view the new configuration through the command:

Get-MsolDomainFederationSettings

Create SAML 2.0 Application in Monokee

At this point the only thing missing is to create the saml application on the Monokee side.

The following steps will guide you through the process of setting up the SAML application associated to the Microsoft 365 tenant:

  1. Navigate to your Monokee custom fully qualified domain name (FQDN) or if you haven't set up a custom FQDN, go to Monokee's default page and enter your domain ID. Then, enter your login credentials to access your account.

  2. Open the left sidebar and select Applications from the menu.

  3. This will display a list of applications. To create the application, click the Add button located in the top right corner of the table. Then, select SAML Application and click Add.

Add SAML 2.0 Application
Figure 6 - Add SAML 2.0 Application
  1. Monokee will open the General Configuration step.

  2. Set the Name of you application. For example Microsoft 365.

  3. Leave the URL parameter empty.

  4. Optionally, set a Description for your application, for example Microsoft 365 SAML 2.0 integration.

  5. Leave the Hide this application from the application broker parameter unchecked, this will allow you to see the application in Monokee Application Broker.

  6. You can load an optional application icon using the Load From File or Load by URL options.

  7. Skip the Protect with flow configuration. In this way the default Authentication Flow will protect this app.

  8. Click Create to proceed to the SAML 2.0 specific configuration. You will be referred to the Service Provider Configuration step.

General Application Configuration
Figure 7 - General Application Configuration
  1. In the Service Provider metadata section you can load the Microsoft 365 metadata, you can find it at this Microsoft 365 url. You can load it directly pasting this url in the field Load by URL. This operation will automatically fill all the fields on this step.
Load Metadata from Url
Figure 8 - Load Metadata from Url
  1. Click Next to proceed to the Additional Configuration step.

  2. In the Additional Configuration section, in the Identity Provider select choose the identity provider created before Microsoft 365 IDP SAML 2.0, in Signature algorithm choose the value http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 and in Digest algorithm the value http://www.w3.org/2001/04/xmlenc#sha256.

  3. All the fields in Identity provider signing options must be kept unchecked.

IDP App Configuration
Figure 9 - IDP App Configuration
  1. Click Next to proceed to the last step Response Statement Configuration.

  2. In the Authentication statement options select urn:oasis:names:tc:SAML:2.0:nameid-format:persistent as Subject format and urn:oasis:names:tc:SAML:2.0:cm:bearer as Subject confirmation method.

Subject Format and Confirmation Method
Figure 10 - Subject Format and Confirmation Method
  1. In the Subject mapping rule you must specify the attribute to be mapped with the subject. To do so, follow the steps:
    • Click the pencil icon next to subject label
    • Click the Add button, a dialog will appear
    • In the Value select present in the dialog choose the attribute AzureImmutableID
    • Click the Add button in the dialog
Subject Rule Configuration
Figure 11 - Subject Rule Configuration
  1. In the Attribute statement section, you must specify the IDPEmail attribute that Microsoft 365 uses to identify user. In order to achieve this, follow the steps:
    • Click New rule and insert IDPEmail
    • Click Add
    • Choose AzureIDPEmail from available items
    • Click Add
Attribute Statement Configuration
Figure 12 - Attribute Statement Configuration
  1. Click the bottom right corner Create button to save the configuration.

You can now associate the newly created application with the users and groups for which you need to grant access to the application.

Test the correct functioning of the configuration

To test that the configurations you have made are working properly, you can value the AzureImmutableID and AzureIDPEmail attributes for your user and associate the application with him.

The test can be taken for IDP initiated and SP initiated access.

Regarding IDP initiated access, navigate to application broker, a card related to the newly created Microsoft 365 application should have appeared. Click on it to test that the configuration is working properly.

Microsoft 365 IDP Initiated login
Figure 13 - Microsoft 365 IDP Initiated login

Upon clicking it, a new browser tab will be opened where you will run the application protection flow and then you will be rendered to Microsoft 365.

To test the SP initiated flow, you can navigate directly to the Microsoft 365 login page, after entering your email, you will be redirected to the Monokee login flow. A as in the previous case, upon login, you will access to Microsoft 365 with your user.

Microsoft 365 SP Initiated login
Figure 14 - Microsoft 365 SP Initiated login

In both cases, if all the configurations have been done correctly, you will log in to your Microsoft 365 restricted area.