Skip to content

Commit

Permalink
update: IdP articles (#494)
Browse files Browse the repository at this point in the history
  • Loading branch information
@staceysalamon-aiven
staceysalamon-aiven authored Oct 18, 2024
1 parent ef43930 commit 0e6e80f
Show file tree
Hide file tree
Showing 15 changed files with 419 additions and 330 deletions.
2 changes: 1 addition & 1 deletion docs/get-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ Make your organization users managed users by verifiying a domain and configurin
identity provider.

Aiven also supports automatic
[user provisioning with Okta](/docs/platform/howto/okta-user-provisioning-with-scim)
[user provisioning with Okta](/docs/platform/howto/saml/add-okta-idp)
through System for Cross-domain Identity Management (SCIM).

<GridContainer columns={3}>
Expand Down
11 changes: 6 additions & 5 deletions docs/platform/howto/list-authentication.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@
title: Authentication methods
---

Browse through instructions for common Aiven platform tasks related to
managing your password or other authentication methods.
Users can authenticate to the Aiven platform using a password, single sign-on (SSO), or [tokens](/docs/platform/concepts/authentication-tokens). The available authentication methods depend on the organization's [authentication policy](/docs/platform/howto/set-authentication-policies).

import DocCardList from '@theme/DocCardList';

<DocCardList />
Organization admin set these policies to restrict or require specific
authentication methods for all users in an organization. They can also set up SSO
through their preferred [identity provider](/docs/platform/howto/list-identity-providers).
For an additional layer of security, Aiven also supports
[two-factor authentication](/docs/platform/howto/set-authentication-policies).
57 changes: 54 additions & 3 deletions docs/platform/howto/list-identity-providers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,59 @@ title: Identity providers and SAML authentication
sidebar_label: Identity providers
---

Give your organization users access to Aiven through SAML-based single sign-on (SSO) with your preferred identity provider.
Set up single sign-on (SSO) access to Aiven through a Security Assertion Markup Language (SAML) compliant identity provider (IdP). This lets you centrally manage your users in your IdP while giving them a seamless login experience.

import DocCardList from '@theme/DocCardList';
Every IdP must be linked to a domain in Aiven. After you
[verify that you own a domain](/docs/platform/howto/manage-domains), the users in your
organization become managed users, which provides a higher level of security for your
organization by controlling things like
[how these users log in](/docs/platform/howto/set-authentication-policies).

<DocCardList />
With a verified domain you can add an IdP. All users with an email address from
the verified domain are automatically authenticated with the linked IdP. With
IdP-initiated SSO enabled, users can log in to Aiven directly from the IdP.

Aiven also supports System for Cross-domain Identity Management (SCIM) for Okta to automatically
provision, update, and deactivate user identities from your IdP.
With automatic provisioning you don’t need to manually create organization users.

When adding an IdP you link it to the verified domain
and can set up SCIM at the same time.

## Limitations

You can link each verified domain to only one IdP. If you set up user provisioning with
SCIM, you should only make changes to user details in the IdP.

## Security best practices

It’s recommended to verify your domains in Aiven even if you don’t use SSO. When
configuring an IdP it's best to enable the following SAML security settings:

- **Require assertion to be signed**: Verifies assertions were issued by a trusted party
and have not been tampered with.
- **Sign authorization request sent to IdP**: Ensures authenticity and integrity with a
digital signature.

The [authentication policy](/docs/platform/howto/set-authentication-policies) for the
organization is also an important component in securing access through an IdP. At a
minimum, use these settings for your authentication policy:

- Don't allow password authentication
- Require log in with this organization's identity provider

To limit access further, also consider these authentication policy settings:

- **Don't allow third-party authentication**: This combined with the preceding password and
organization identity provider settings ensures that users only log in to the Console
with your chosen IdP.
- **Don't allow users to create personal tokens**: This prevents users from accessing
organization resources through the API.

If you allow your users to create personal tokens, you can still make these more
secure by enabling **Require users to be logged in with an allowed
authentication method**. This means that users cannot access your organization's
resources with a token they created when logged in with another organization's
allowed authentication methods or a previously allowed method.
This setting also gives you the flexibility to change the authentication policy at any
time because tokens that are no longer compliant with the new policy cannot be used.
32 changes: 16 additions & 16 deletions docs/platform/howto/saml/add-auth0-idp.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,17 @@
title: Add Auth0 as an identity provider
sidebar_label: Auth0
---
<!-- vale off -->
import IdPStep1 from "@site/static/includes/idp-step1.md";
import IdPStep3 from "@site/static/includes/idp-step3.md"

Use [Auth0](https://auth0.com/) to give your organization users single sign-on (SSO) access to Aiven.
<!-- vale on -->

## Prerequisite
Use [Auth0](https://auth0.com/) to give your organization users single sign-on (SSO) access to Aiven.

Add Auth0 as a SAML
[identity provider](/docs/platform/howto/saml/add-identity-providers#add-idp-aiven-console) in the Console.
<IdPStep1/>

## Configure SAML on Auth0 {#configure-saml-auth0}
## Step 2: Configure SAML on Auth0

1. Log in to [your Auth0 account](https://manage.auth0.com).
2. Select **Applications**.
Expand All @@ -20,7 +22,7 @@ Add Auth0 as a SAML
6. After your application is created, go to the **Addons** tab.
7. Enable the **SAML 2 WEB APP** option.
8. Click the **SAML 2 WEB APP** option. The **Settings** tab opens.
9. Set the `Application Callback URL` to the `ACS URL` from the Aiven
9. Set the **Application Callback URL** to the **ACS URL** from the Aiven
Console.
10. In the **Settings** section for the Application Callback URL, remove
the existing configuration and add the following field mapping
Expand All @@ -38,17 +40,15 @@ Add Auth0 as a SAML

11. Click **Enable** and **Save**.
12. On the **Usage** tab, make a note of the
`Identity Provider Login URL`, `Issuer URN`, and
`Identity Provider Certificate`. These are needed for the SAML
**Identity Provider Login URL**, **Issuer URN**, and
**Identity Provider Certificate**. These are needed for the SAML
configuration in Aiven Console.

## Finish the configuration in Aiven

Go back to the Aiven Console to
[configure the IdP](/docs/platform/howto/saml/add-identity-providers#configure-idp-aiven-console) and complete the setup.
## Step 3: Finish the configuration in Aiven

## Troubleshooting
Go back to the Aiven Console to complete setting up the IdP. If you saved your IdP as a
draft, you can open the settings by clicking the name of the IdP.

If you have issues, you can use the [SAML Tracer browser
extension](https://addons.mozilla.org/firefox/addon/saml-tracer/) to
check the process step by step.
1. In the **IDP URL** field, enter the Auth0 **Identity Provider Login URL**.
1. In the **Entity Id** field, enter the Auth0 **Issuer URN**.
<IdPStep3/>
67 changes: 33 additions & 34 deletions docs/platform/howto/saml/add-azure-idp.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,70 +2,74 @@
title: Add Microsoft Azure Active Directory as an identity provider
sidebar_label: Microsoft Azure Active Directory
---
<!-- vale off -->
import IdPStep1 from "@site/static/includes/idp-step1.md";
import IdPStep3 from "@site/static/includes/idp-step3.md"

Use [Microsoft Azure Active Directory (AD)](https://azure.microsoft.com/en-us/products/active-directory/) to give your organization users single sign-on (SSO) access to Aiven.
<!-- vale on -->

## Prerequisite steps in Aiven Console
Use [Microsoft Azure Active Directory (AD)](https://azure.microsoft.com/en-us/products/active-directory/) to give your organization users single sign-on (SSO) access to Aiven.

Add Azure as a SAML
[identity provider](/docs/platform/howto/saml/add-identity-providers#add-idp-aiven-console) in the Console.
<IdPStep1/>

## Configure SAML on Microsoft Azure {#configure-saml-azure}
## Step 2: Configure SAML on Microsoft Azure

### Set up an Azure application

1. Log in to [Microsoft Azure](https://portal.azure.com/).
1. Got to **Enterprise applications**.
1. Select **All applications**.
1. Go to **Enterprise applications**.
1. Click **All applications**.
1. Click **New application**.
1. Select the **Add from the gallery** search bar and use the **Azure
AD SAML Toolkit**.
1. Click the **Add from the gallery** search bar and use the **Azure AD SAML Toolkit**.
1. Click **Add**.
1. Go back to the **Enterprise applications** list.

:::note
The newly created application might not be visible yet. You can use
The newly created application might not be visible. You can use
the **All applications** filter to see the new application.
:::

1. Click the name of the new application. The configuration opens.
1. Select **Single sign-on** configuration.
1. Click the name of the new application.
1. Click **Single sign-on**.
1. Select **SAML** as the single sign-on method.
1. Add the following parameters to the **Basic SAML Configuration**:

| Parameter | Value |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `Identifier (Entity ID)` | `https://api.aiven.io/v1/sso/saml/account/{account_id}/method/{account_authentication_method_id}/metadata` |
| `Reply URL (Assertion Consumer Service URL)` | `https://api.aiven.io/v1/sso/saml/account/{account_id}/method/{account_authentication_method_id}/acs` |
| `Sign on URL` | `https://console.aiven.io` |
| Parameter | Value |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| Identifier (Entity ID) | https://api.aiven.io/v1/sso/saml/account/{account_id}/method/{account_authentication_method_id}/metadata |
| Reply URL (Assertion Consumer Service URL) | https://api.aiven.io/v1/sso/saml/account/{account_id}/method/{account_authentication_method_id}/acs |
| Sign on URL | https://console.aiven.io |

1. Click **Save**.

### Create a claim and add users

1. In the **User Attributes & Claims**, click **Add a new claim**.
1. Create an attribute with the following data:
1. Create an attribute with the following:

| Parameter | Value |
| ------------------ | ----------- |
| `Name` | `email` |
| `Source` | `Attribute` |
| `Source Attribute` | `user.mail` |
| Parameter | Value |
| ---------------- | --------- |
| Name | email |
| Source | Attribute |
| Source Attribute | user.mail |

1. Download the **Certificate (Base64)** from the **SAML Signing
Certificate** section.
1. Download the **Certificate (Base64)** from the **SAML Signing Certificate** section.
1. Go to **Users and groups** and click **Add user**.
1. Select the users that will use Azure AD to log in to Aiven.
1. Click **Assign**.

## Finish the configuration in Aiven
## Step 3: Finish the configuration in Aiven

Go back to the Aiven Console to
[configure the IdP](/docs/platform/howto/saml/add-identity-providers#configure-idp-aiven-console) and complete the setup.
Go back to the Aiven Console to complete setting up the IdP. If you saved your IdP as a
draft, you can open the settings by clicking the name of the IdP.

1. In the **IDP URL** field, enter the **Login URL** from Azure.
1. In the **Entity Id** field, enter the **Azure AD Identifier** from Azure.
<IdPStep3/>

## Troubleshooting

If you get an error message suggesting you contact your administrator:
If you get an error message to contact your administrator:

1. Go to the Microsoft Azure AD user profile for the users.
1. In **Contact Info**, check whether the **Email** field is blank.
Expand All @@ -78,8 +82,3 @@ If it is blank, there are two possible solutions:
- In **Contact Info**, if none of the **Alternate email** fields are
blank, try changing the **User Attributes & Claims** to
`email = user.othermail`.

If you still have login issues, you can use the [SAML Tracer browser
extension](https://addons.mozilla.org/firefox/addon/saml-tracer/) to
check the process step by step. If this doesn't work, get in touch with
our support team at [[email protected]](mailto:[email protected]).
79 changes: 39 additions & 40 deletions docs/platform/howto/saml/add-fusionauth-idp.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,42 +2,43 @@
title: Add FusionAuth as an identity provider
sidebar_label: FusionAuth
---
<!-- vale off -->
import IdPStep1 from "@site/static/includes/idp-step1.md";
import IdPStep3 from "@site/static/includes/idp-step3.md"

Use [FusionAuth](https://fusionauth.io/) to give your organization users single sign-on (SSO) access to Aiven.
<!-- vale on -->

## Prerequisite steps in Aiven Console
Use [FusionAuth](https://fusionauth.io/) to give your organization users single sign-on (SSO) access to Aiven.

Add FusionAuth as a SAML
[identity provider](/docs/platform/howto/saml/add-identity-providers#add-idp-aiven-console) in the Console.
<IdPStep1/>

## Configure SAML on FusionAuth {#configure-saml-fusionauth}
## Step 2: Configure SAML on FusionAuth

The setup on FusionAuth has three parts:

- create an API key
- generate a custom RSA certificate
- create an application
- Create an API key
- Generate a custom RSA certificate
- Create an application

Create an API Key in your FusionAuth instance:
### Create an API key

1. In FusionAuth, go to **Settings** > **API Keys**.
1. Click the **Add** icon.
1. Enter a description for the key. Example: `Certificate generator`.
1. In the **Endpoints** list, find `/api/key/import`.
1. Enter a description for the key.
1. In the **Endpoints** list, find **/api/key/import**.
1. Toggle on **POST**.
1. Click the **Save** icon.

![Creating API Key.](/images/content/platform/howto/saml/fusionauth/create-api-key.png)
![Creating an API key.](/images/content/platform/howto/saml/fusionauth/create-api-key.png)

1. On the **API Keys** page, find your new key and click the value
in the **Key** column.
1. On the **API Keys** page, find your key and click the value in the **Key** column.

1. Copy the whole key. You'll use this for the script.

![Grabbing API Key.](/images/content/platform/howto/saml/fusionauth/grab-api-key.png)
![Copying the API key value.](/images/content/platform/howto/saml/fusionauth/grab-api-key.png)

1. Clone [the FusionAuth example scripts GitHub
repository](https://github.com/FusionAuth/fusionauth-example-scripts).
1. To clone the [FusionAuth example scripts GitHub
repository](https://github.com/FusionAuth/fusionauth-example-scripts), run:

```shell
git clone [email protected]:FusionAuth/fusionauth-example-scripts.git
Expand All @@ -50,33 +51,31 @@ Create an API Key in your FusionAuth instance:
./generate-certificate
```

1. Give the key a meaningful name (for example, "Aiven key").
1. Name the key.

1. Copy the generated certificate created by the script.

1. Copy the generated certificate that the script creates. You now have
a certificate in the **Key Master** in your FusionAuth instance.
You now have a certificate in the **Key Master** in your FusionAuth instance.

Create an application in your FusionAuth instance:
### Create an application

1. In **Applications**, click the **Add** icon.
1. Enter a name for the application (for example, "Aiven").
1. On the **SAML** tab, and toggle on the **Enabled** switch.
1. Paste the **Metadata URL** and **ACS URL** you copied from the Aiven
Console to the **Issuer** and **Authorized redirect URLs** fields in
your FusionAuth application, respectively.

| Aiven | FusionAuth |
| ------------ | ------------------------ |
| Metadata URL | Issuer |
| ACS URL | Authorized redirect URLs |

1. In the **Authentication response** section, change the **Signing
key** to the API key you created.
1. Click the **Save** icon to save your application.
1. Enter a name for the application.
1. On the **SAML** tab, toggle on **Enabled**.
1. In the **Issuer** field, enter the **Metadata URL** from the Aiven Console.
1. In the **Authorized redirect URLs** field, enter the **ACS URL** from the Aiven Console.
1. In the **Authentication response** section, change the **Signing key** to the
API key you created.
1. Click the **Save** icon.
1. On the **Applications** page, click the magnifying glass.
1. In the **SAML v2 Integration details** section, copy the **Entity
Id** and **Login URL**.
1. In the **SAML v2 Integration details** section,
copy the **Entity Id** and **Login URL**.

## Step 3: Finish the configuration in Aiven

## Finish the configuration in Aiven
Go back to the Aiven Console to complete setting up the IdP. If you saved your IdP as a
draft, you can open the settings by clicking the name of the IdP.

Go back to the Aiven Console to
[configure the IdP](/docs/platform/howto/saml/add-identity-providers#configure-idp-aiven-console) and complete the setup.
1. In the **IDP URL** field, enter the **Login URL** from FusionAuth.
1. In the **Entity ID** field, enter the **Entity ID** from FusionAuth.
<IdPStep3/>
Loading

0 comments on commit 0e6e80f

Please sign in to comment.