diff options
Diffstat (limited to 'server/sonar-docs/src/pages/instance-administration')
| -rw-r--r-- | server/sonar-docs/src/pages/instance-administration/authentication/saml/okta.md | 123 |
1 files changed, 121 insertions, 2 deletions
diff --git a/server/sonar-docs/src/pages/instance-administration/authentication/saml/okta.md b/server/sonar-docs/src/pages/instance-administration/authentication/saml/okta.md index 294265069c2..e27727e8b31 100644 --- a/server/sonar-docs/src/pages/instance-administration/authentication/saml/okta.md +++ b/server/sonar-docs/src/pages/instance-administration/authentication/saml/okta.md @@ -3,5 +3,124 @@ title: How to setup Okta url: /instance-administration/authentication/saml/okta/ --- -### Using Okta as a SAML Identity Provider -The following content may be useful if you're using Okta as a SAML Identity Provider. +## Using Okta as a SAML Identity Provider + +The following example may be useful if you are using Okta as a SAML Identity Provider. +Note that Okta does not support service provider signed requests even if they are enabled on the SonarQube side. + + +### Create a new application in Okta admin dashboard + +1. Under **Applications**, choose **Create App Integration**. + +  + +2. Choose **SAML 2.0** in the **Sign-in Method** dialog. + +3. Under **General Settings**, fill in **App name** with *SonarQube* (or another name that you prefer) and opt-in to **Do not display application icon to users**. + +  + + +### Configure SAML settings + +Under *General Settings*, configure the following fields: + +- **Single sign on URL**: `<Your SonarQube URL>/oauth2/callback/saml` (e.g., `https://sonarqube.mycompany.com/oauth2/callback/saml`). + +- **Audience URI (SP Entity ID)**: Something like `sonarqube` (SonarQube default value). It must not contain whitespace. + + + +(Optional) If you want to enable assertion encryption, expand *Show Advanced Settings* and configure the following fields: + +- **Assertion Encryption**: Choose *Encrypted*. + +- **Encryption Algorithm**: Choose *AES256-GCM* for high security. + +- **Key Transport Algorithm**: Choose *RSA-OAEP*. + +- **Encryption Certificate**: Add the service provider (SonarQube) certificate. + + + +Under **Attribute Statements**, add the following attribute mappings: + +- Create a mapping for the *name*: + + 1. **Name**: `name`. + + 2. **Name format**: *Unspecified*. + + 3. **Value**: Choose `user.firstName`. + +- Create a mapping for the *login*: + + 1. **Name**: `login`. + + 2. **Name format**: *Unspecified*. + + 3. **Value**: Choose `user.login`. + +- (Optional) Create a mapping for the *email*: + + 1. **Name**: `email`. + + 2. **Name format**: *Unspecified*. + + 3. **Value**: Choose `user.email`. + +  + +- (Optional) Under *Group Attribute Statements*: + + 1. **Name**: `groups`. + + 2. **Name format**: *Unspecified*. + + 3. **Filter**: Choose *Matches regex* and set the value to `.*`. + +  + +Click **Finish** in the **Feedback** dialog to confirm the creation of the application. + +After the application creation, navigate to the **Sign On** tab of the *SonarQube* application in Okta. + + + +Next to the **SAML Signing Certificates** subsection, you will find the configurations needed for setting up SonarQube, under **View SAML setup instructions**. + + + + +## In SonarQube, Configure SAML authentication + +Go to **[Administration > Configuration > General Settings > Authentication > SAML](/#sonarqube-admin#/admin/settings?category=authentication)** + +- **Enabled**: *true*. + +- **Application ID**: The value of the *Audience URI (SP Entity ID)* you set in Okta (for example, `sonarqube`). + +- **Provider ID**: The value of *Identity Provider Issuer* provided in **View SAML setup instructions** from Okta. + +- **SAML login url**: The value of *Identity Provider Single Sign-On URL* provided in **View SAML setup instructions** from Okta. + +- **Identity provider certificate**: The value of *X.509 Certificate* provided in **View SAML setup instructions** from Okta. + +- **SAML user login attribute**: `login` (or whatever you configured above when doing the mapping). + +- **SAML user name attribute**: `name` (or whatever you configured above when doing the mapping). + +- (Optional) **SAML user email attribute**: `email` (or whatever you configured above when doing the mapping). + +- (Optional) **SAML group attribute** `groups` (or whatever you configured above when doing the mapping). + +- **Sign requests**: Not supported for Okta. + +- **Service provider private key**: The private key is required for assertion encryption support and should be provided for SonarQube in `PKCS8` format without password protection. + +- **Service provider certificate**: The certificate is required for assertion encryption support and should be shared with Okta in order to activate the assertion encryption. + +You can find instructions for converting to different key formats [here](https://manpages.ubuntu.com/manpages/focal/man1/pkcs8.1ssl.html). + +In the login form, the new button **Log in with SAML** allows users to connect with their SAML account. |