-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* structure and first okta proc * add okta images * just a backup while I am blocked * more backup * add draft of entra scim * backup until I meet with Ben * backup morning work * finished Okta YAYY * fix image link * exclude MS to get Okta in * nits * spelling expects * spelling * add MS back in * image fixes * image fixes * sidebar tweaks * per chris-rock feedback * reformat graphql -- just one * remove old SAML file * return to original Okta GQL sample file
- Loading branch information
1 parent
79c1277
commit b76d164
Showing
25 changed files
with
423 additions
and
109 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,193 @@ | ||
| --- | ||
| title: Manage Mondoo Access with Microsoft Entra ID and SCIM | ||
| sidebar_label: Manage Access with Entra (SCIM) | ||
| sidebar_position: 4 | ||
| description: Configure Microsoft Entra as an authentication provider for Mondoo Platform. | ||
| image: /img/featured_img/mondoo-feature.jpg | ||
| --- | ||
|
|
||
| Integrate Mondoo with Microsoft Entra ID with the System for Cross-domain Identity Management 2.0 (SCIM 2.0) protocol so you can: | ||
|
|
||
| - Enable users to log into Mondoo with their Entra ID account | ||
| - Control who has access to Mondoo using Entra ID | ||
| - Centrally manage users with Entra ID | ||
|
|
||
| Configuring single sign-on allows Entra to handle authentication (verifying that a user is who they say they are) for Mondoo. Configuring user management allows you to use Entra user groups to authorize access to Mondoo. | ||
|
|
||
| You can choose to set up Entra single sign-on but not Okta user management. However, you can't use Entra for Mondoo user management without first setting up Entra single sign-on. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| To configure the integration, you need: | ||
|
|
||
| - Administrator access to your Entra ID account | ||
| - A privately hosted Mondoo [Enterprise account](https://mondoo.com/pricing) | ||
|
|
||
| ## Configure Entra single sign-on for Mondoo (using OIDC) | ||
|
|
||
| To allow users to log into the Mondoo Console with their Entra-provided credentials, you create an Entra app registration for Mondoo. This implementation relies on [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) to authenticate users. | ||
|
|
||
| 1. Log into the Microsoft Entra admin center. | ||
|
|
||
| 2. In the left menu, select **App registrations** and, in the toolbar, select **+ New application**. | ||
|
|
||
|  | ||
|
|
||
| 3. In the **Name** box, enter a name for the app registration, such as Mondoo. | ||
|
|
||
| 4. Under **Supported account types**, leave **Accounts in this organizational directory only (Mondoo only - Single tenant)** selected. | ||
|
|
||
| 5. Under **Redirect URI (Optional)**, select **Single-page Application (SPA)** and type the URL that you use to access the Mondoo console for your Mondoo Enterprise instance, such as `https://console.YOUR-COMPANY.mondoo.com`. | ||
|
|
||
| 6. Select the **Register** button. | ||
|
|
||
|  | ||
|
|
||
| 7. Copy the **Application (client) ID** and share it with your Mondoo representative. | ||
|
|
||
| 8. In the toolbar, select **Endpoints**. | ||
|
|
||
|  | ||
|
|
||
| 9. Copy the **OAuth 2.0 token endpoint (v2)** and share it with your Mondoo representative. | ||
|
|
||
| The Mondoo team uses the **Application (client) ID** and **OAuth 2.0 token endpoint (v2)** to enable Entra single sign-on for your Mondoo Enterprise account and prepare your instance for SCIM compatibility. | ||
|
|
||
| ## Manage Mondoo users with Entra (using SCIM) | ||
|
|
||
| To centralize user management for your organization, give your Entra account full control over who can access organizations and spaces and perform different tasks in Mondoo. This implementation relies on the System for Cross-domain Identity Management (SCIM) protocol. Mondoo's SCIM support lets you give Entra groups access to organizations and spaces in your Mondoo Enterprise instance. | ||
|
|
||
| :::note | ||
|
|
||
| Before you set up Entra user management for Mondoo, you must first configure Entra single sign-on by following the steps above. | ||
|
|
||
| ::: | ||
|
|
||
| ### Step A: Create a new Mondoo API token | ||
|
|
||
| 1. In the Mondoo Console, [create a new API token with **edit** permission to your Mondoo **organization**.](https://mondoo.com/docs/platform/maintain/access/api-tokens/#generate-an-api-token-for-access-to-all-spaces-in-an-organization). | ||
|
|
||
| 2. Copy the generated token and save it. You need it for many of the steps below. | ||
|
|
||
| ### Step B: Identify your SCIM base URL | ||
|
|
||
| Determine your SCIM base URL using the URL you use to access the Mondoo Console: Replace `console` with `api` and add `/scim/v2`. So if your Mondoo Console URL is: | ||
|
|
||
| `https://console.YOUR-COMPANY-NAME.mondoo.com` | ||
|
|
||
| then your SCIM base URL is: | ||
|
|
||
| `https://api.YOUR-COMPANY-NAME.mondoo.com/scim/v2` | ||
|
|
||
| ### Step C: Verify that SCIM is enabled for your Mondoo instance | ||
|
|
||
| Confirm that the Mondoo team has successfully enabled SCIM support for your Mondoo Enterprise instance. | ||
|
|
||
| - For `YOUR-API-TOKEN`, substitute the token you created in the step above. | ||
|
|
||
| - For `YOUR-SCIM-BASE-URL`, substitute the SCIM base URL you identified in the step above. | ||
|
|
||
| ```bash | ||
| $ TOKEN='YOUR-API-TOKEN' | ||
| $ curl -i -X GET -H "authorization: Bearer $TOKEN" YOUR-SCIM-BASE-URL/Users | ||
| HTTP/2 200 | ||
| content-type: application/scim+json | ||
| vary: Origin | ||
| vary: Accept-Encoding | ||
| date: Thu, 16 May 2024 21:09:36 GMT | ||
| content-length: 130 | ||
| via: 1.1 google | ||
| alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000 | ||
|
|
||
| {"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],"totalResults":0,"itemsPerPage":0,"startIndex":0,"Resources":[]} | ||
| ``` | ||
|
|
||
| If this test is unsuccessful, contact your Mondoo representative. | ||
|
|
||
| ### Step D: Create a SCIM application in Entra | ||
|
|
||
| 1. Log into the Microsoft Entra admin center. | ||
|
|
||
| 2. In the left menu, under **Applications**, select **Enterprise Applications**. | ||
|
|
||
|  | ||
|
|
||
| 3. In the toolbar, select **+ New Application** and then select **Create your own application**. | ||
|
|
||
|  | ||
|
|
||
| 4. Type the name `Mondoo SCIM`, leave **Integrate any other application you don't find in the gallery (Non-gallery)** selected, and select the **Next** button. | ||
|
|
||
| 5. In the left menu, select **Provisioning** and again in the left menu select **Provisioning**. | ||
|
|
||
|  | ||
|
|
||
| 6. In the **Provisioning Mode** box, select **Automatic**. | ||
|
|
||
|  | ||
|
|
||
| 7. In the **Tenant URL** box, enter the SCIM base URL you identified in the step above. | ||
|
|
||
| 8. In the **Secret Token** box, paste the Mondoo API token you created in the step above. | ||
|
|
||
| 9. On the Provisioning toolbar, select **Save**. | ||
|
|
||
| 10. Select the **Mappings** drop-down and select **Provision Microsoft Entra ID Groups**. | ||
|
|
||
| 11. Scroll down to the **Attribute Mappings** and make sure that these attributes are mapped: | ||
|
|
||
| | Mondoo Attribute | Microsoft Entra ID Attribute | | ||
| |------------------|------------------------------| | ||
| | userName | userPrincipalName | | ||
| | displayName | displayName | | ||
| | externalId | objectId | | ||
|
|
||
|
|
||
| ### Step E: Identify Mondoo organization and space IDs | ||
|
|
||
| To find the ID of an organization and a space: | ||
|
|
||
| 1. In the top navigation bar of the Mondoo Console, select your region. Mondoo displays all organizations in the region. | ||
|
|
||
|  | ||
|
|
||
| Note each organization's ID in smaller text below the organization name. In the image above, the organization IDs are `blissful-mcnulty-255959` and `dewey-marzipan`. | ||
|
|
||
| 2. Select the organization containing the space you want and, in the side navigation bar, select **Spaces**. | ||
|
|
||
|  | ||
|
|
||
| 3. Select the space you want and, in the side navigation bar, select **Settings**. | ||
|
|
||
|  | ||
|
|
||
| On the **General Settings** tab, note the ID of the space in the first field, **Name (A unique ID used to identify this space)**. In the image above, the space ID is `bunny-ears-chopsticks`. | ||
|
|
||
| ### Step G: Grant Mondoo organization and space access using cURL | ||
|
|
||
| Create a new file named `scim-mapping.gql` and containing a GraphQL request based on this sample: | ||
|
|
||
| ```gql | ||
| { | ||
| "query": "mutation {\n setScimGroupMapping(\n input: {\n orgMrn: \"//captain.api.mondoo.app/organizations/YOUR-ORG-ID\",\n group: \"YOUR-OKTA-GROUP\",\n mappings: [{\n orgMrn: \"//captain.api.mondoo.app/organizations/YOUR-ORG-ID\",\n #spaceMrn: \"//captain.api.mondoo.app/spaces/YOUR-SPACE-ID\",\n iamRole: \"//iam.api.mondoo.app/roles/editor\"\n },{\n #orgMrn: \"//captain.api.mondoo.app/organizations/YOUR-ORG-ID\",\n spaceMrn: \"//captain.api.mondoo.app/spaces/YOUR-SPACE-ID\",\n iamRole: \"//iam.api.mondoo.app/roles/editor\"\n },{\n #orgMrn: \"//captain.api.mondoo.app/organizations/YOUR-ORG-ID\",\n spaceMrn: \"//captain.api.mondoo.app/spaces/YOUR-SPACE-ID\",\n iamRole: \"//iam.api.mondoo.app/roles/viewer\"\n }]\n }\n ) {\n group\n }\n}" | ||
| } | ||
| ``` | ||
|
|
||
| | For... | Substitute... | | ||
| | -------------- | -------------------------------------------------------------------- | | ||
| | YOUR-ORG-ID | The ID of the organization to which you want to grant a group access | | ||
| | YOUR-SPACE-ID | The ID of the space to which you want to grant a group access | | ||
|
|
||
| Execute the query: | ||
|
|
||
| ```bash | ||
| $ export TOKEN='eyJhbGciOiJF...' | ||
| $ curl -i -X POST -H "content-type: application/json" \ | ||
| -H "authorization: Bearer $TOKEN" -d @scim-mapping.gql \ | ||
| https://api.spacecat.mondoo.com/query | ||
| ``` | ||
|
|
||
| ## Learn more | ||
|
|
||
| - To learn more about SCIM, read [System for Cross-domain Identity Management](https://scim.cloud/). | ||
| - To learn more about app registrations and enterprise apps in Microsoft Entra, read Microsoft's [Application management documentation](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/). |
Oops, something went wrong.