Reference SAML configuration

In this section, you can find the configurations required for setting up integration via SAML between your instance of IDE Services and a third-party authentication provider. The setup is performed in both IDE Services and your authentication provider's system.

Set up IDE Services on your authentication provider's side

Start by configuring the integration with IDE Services on the side of your authentication provider. The exact steps will differ depending on your authentication provider.

Set up the metadata by generating or obtaining the metadata file on the authentication provider's side. Such files usually include the following information: the provider's entity identifier, SSO URL, and public certificate.
Define which user attributes like an email, username, and role, will be included in the SAML assertion sent to the authentication provider.
Create and configure a service provider entry:
- In the administration console, create a new service provider entry. You will need to specify the service provider's entity identifier, which is any unique identifier to be added to saml.sp-id, and the Assertion Consumer Service URL or Single Sign-On URL: '<ide-services-url>/api/saml/authenticated'.
- (Optional) Map the attributes of the authentication provider to the attributes that the service provider expects.
- (Optional) Enable validation of SAML requests with signature certificates and upload the service provider certificate.
- (Optional) Enable response signatures.
- (Optional) Enable response encryption and upload the service provider certificate.

Generate the necessary keys and certificates

Generate a local certificate and private key for the SAML service provider

Run the following command:
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout local.key -out local.crt
(Optional) If encryption is enabled, upload the local certificate to the authentication provider's system. IDE Services will use the generated key for decrypting the SAML response.

Generate an RSA key pair

IDE Services manages the internal JWT token to support sessions. For this purpose, it is required to generate an RSA key pair.

Run the following command:
openssl genrsa -out private_key.pem 4096 openssl rsa -pubout -in private_key.pem -out public_key.pem # Convert the private key to pkcs8 to import it from Java openssl pkcs8 -topk8 -in private_key.pem -inform pem -out private_key_pkcs8.pem -outform pem -nocrypt

Configure provider details in your server configuration file

Use these examples to configure connection to your authentication server in your server configuration file — application.yaml or values.yaml (for Helm installations.)

                    
tbe:
    auth:
        token-url: '${tbe.deployment.url}/api/saml/token'
        jwt-certs-url: '${tbe.deployment.url}/api/saml/jwks.json'
        saml:
            enabled: true
            sp-id: '${tbe.deployment.url}/api/saml/metadata'
            sp-assertion-consumer-service-url: '${tbe.deployment.url}/api/saml/authenticated'
            sp-x509cert: <local.crt>
            sp-private-key: <local.key>
            sso-url: '<per configuration>'
            idp-id: 'https://saml.example.com/id'
            idp-x509cert: <x509 certificate>
            cert-algorithm: sha256
            idp-http-method: 'POST' #optional
            attribute-mapping: #optional
                email: email
                firstName: first_name
                lastName: last_name
                fullName: full_name
            internal:
                token-life: 30m
                refresh-token-life: 30d
                private-key: |
                    <private_key_pkcs8.pem>
                public-key: |
                    <public_key.pem>
                

tbe.auth.token-url: Provide a URL for obtaining an authorization token on the side of your authentication provider.
tbe.auth.jwt-certs-url: Specify a URL to the JSON Web Key (JWK) set that is used to validate JSON Web Tokens (JWT).
tbe.auth.saml.enabled: Enables the use of SAML.
tbe.auth.saml.sp-id: If necessary, specify a unique identifier for IDE Services, which can be used in requests to an external SAML identity provider.
tbe.auth.saml.sp-x509cert: Provide the content of local.crt. This value is used to publish the metadata provided in the certificate.
tbe.auth.saml.sp-private-key: Provide the content of local.key. This value is used for generating a signature and decrypting a SAMLResponse.
tbe.auth.saml.sso-url: An external endpoint of the SAML identity provider used for Single Sign-On. This value can be obtained from an external IdP configuration.
tbe.auth.saml.idp-id: Specify an identifier of the identity provider.
tbe.auth.saml.idp-x509cert: Provide the X509 certificate. This value is used to validate signatures of IdP responses.
tbe.auth.saml.cert-algorithm: Specify SHA-256 as a certificate signing algorithm.
tbe.auth.saml.idp-http-method: Specify the HTTP method type to use in sign-on requests. Possible values: GET, POST.
tbe.auth.saml.attribute-mapping.email: If the email field is named differently on the identity provider's side, specify the field name.
tbe.auth.saml.attribute-mapping.firstName: If the firstName field is named differently on the identity provider's side, specify the field name.
tbe.auth.saml.attribute-mapping.lastName: If the lastName field is named differently on the identity provider's side, specify the field name.
tbe.auth.saml.attribute-mapping.fullName: If the fullName field is named differently on the identity provider's side, specify the field name.
tbe.auth.saml.internal.token-life: Defines the life period of the JWT token issued by the Internal Authorization Server.
tbe.auth.saml.internal.refresh-token-life: Defines the life period of the Refresh JWT token issued by the Internal Authorization Server.
tbe.auth.saml.internal.private-key: Provide the content of the private_key_pkcs8.pem file. This is a private key that will be used to sign internal JWT tokens.
tbe.auth.saml.internal.public-key: Provide the content of the public_key.pem file. This is a public key that will be used to validate internal JWT tokens.

For a full list of authentication properties, refer to Server configuration file.

                    
            ides:
                config:
                    auth:
                        token-url: '${tbe.deployment.url}/api/saml/token'
                        jwt-certs-url: '${tbe.deployment.url}/api/saml/jwks.json'
                        saml:
                            enabled: true
                            sp-id: '${tbe.deployment.url}/api/saml/metadata'
                            sp-assertion-consumer-service-url: '${tbe.deployment.url}/api/saml/authenticated'
                            sp-x509cert: <local.crt>
                            sp-private-key: <local.key>
                            sso-url: '<per configuration>'
                            idp-id: 'https://saml.example.com/id'
                            idp-x509cert: <x509 certificate>
                            cert-algorithm: sha256
                            idp-http-method: 'POST' #optional
                            attribute-mapping: #optional
                                email: email
                                firstName: first_name
                                lastName: last_name
                                fullName: full_name
                            internal:
                                token-life: 30m
                                refresh-token-life: 30d
                                private-key: |
                                    <private_key_pkcs8.pem>
                                public-key: |
                                    <public_key.pem>
                                        
                

ides.config.auth.token-url: Provide a URL for obtaining an authorization token on the side of your authentication provider.
ides.config.auth.jwt-certs-url: Specify a URL to the JSON Web Key (JWK) set that is used to validate JSON Web Tokens (JWT).
ides.config.auth.saml.enabled: Enables the use of SAML.
ides.config.auth.saml.sp-id: If necessary, specify a unique identifier for IDE Services, which can be used in requests to an external SAML identity provider.
ides.config.auth.saml.sp-x509cert: Provide the content of local.crt. This value is used to publish the metadata provided in the certificate.
ides.config.auth.saml.sp-private-key: Provide the content of local.key. This value is used for generating a signature and decrypting a SAMLResponse.
ides.config.auth.saml.sso-url: An external endpoint of the SAML identity provider used for Single Sign-On. This value can be obtained from an external IdP configuration.
ides.config.auth.saml.idp-id: Specify an identifier of the identity provider.
ides.config.auth.saml.idp-x509cert: Provide the X509 certificate. This value is used to validate signatures of IdP responses.
ides.config.auth.saml.cert-algorithm: Specify SHA-256 as a certificate signing algorithm.
ides.config.auth.saml.idp-http-method: Specify the HTTP method type to use in sign-on requests. Possible values: GET, POST.
ides.config.auth.saml.attribute-mapping.email: If the email field is named differently on the identity provider's side, specify the field name.
ides.config.auth.saml.attribute-mapping.firstName: If the firstName field is named differently on the identity provider's side, specify the field name.
ides.config.auth.saml.attribute-mapping.lastName: If the lastName field is named differently on the identity provider's side, specify the field name.
ides.config.auth.saml.attribute-mapping.fullName: If the fullName field is named differently on the identity provider's side, specify the field name.
ides.config.auth.saml.internal.token-life: Defines the life period of the JWT token issued by the Internal Authorization Server.
ides.config.auth.saml.internal.refresh-token-life: Defines the life period of the Refresh JWT token issued by the Internal Authorization Server.
ides.config.auth.saml.internal.private-key: Provide the content of the private_key_pkcs8.pem file. This is a private key that will be used to sign internal JWT tokens.
ides.config.auth.saml.internal.public-key: Provide the content of the public_key.pem file. This is a public key that will be used to validate internal JWT tokens.

For a full list of authentication properties, refer to Values file.

Last modified: 19 August 2024