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.
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.
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 uses the generated key for decrypting SAML responses.
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
Use the following 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>
deployment:
allowed-origins: <Identity-provider-URL>
server:
forward-headers-strategy: NATIVE
- 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.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-x509cert
Provide the X509 certificate. This value is used to validate signatures of IdP responses.
- 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
Specify the duration for which the JWT token, issued by the Internal Authorization Server after a successful SAML login, remains valid. This token is primarily used for making authenticated calls to IDE Services.
- tbe.auth.saml.internal.refresh-token-life
Specify the duration for which the Refresh JWT token, issued by the Internal Authorization Server, remains valid. The refresh token is used to renew the primary JWT token without requiring re-authentication via the SAML provider. If the refresh token expires (30 days by default), the user will need to re-authenticate through the SAML provider.
- 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.
- tbe.deployment.allowed-origins
If necessary, provide a list of CORS origins allowed by the IDE Services Server.
- server.forward-headers-strategy
Define how forwarded headers, such as
X-Forwarded-For
, from a reverse proxy are processed in a Spring Boot application. Possible values:NATIVE
: Uses the native web server's support for handling forwarded headers.FRAMEWORK
: Relies on Spring's custom mechanism to process forwarded headers.
For a full list of authentication properties, refer to Server configuration file.
ides:
config:
allowed-origins: '<Identity-provider-URL>'
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>
configCustomization:
server:
forward-headers-strategy: NATIVE
- 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.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-x509cert
Provide the X509 certificate. This value is used to validate signatures of IdP responses.
- 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
Specify the duration for which the JWT token, issued by the Internal Authorization Server after a successful SAML login, remains valid. This token is primarily used for making authenticated calls to IDE Services.
- ides.config.auth.saml.internal.refresh-token-life
Specify the duration for which the Refresh JWT token, issued by the Internal Authorization Server, remains valid. The refresh token is used to renew the primary JWT token without requiring re-authentication via the SAML provider. If the refresh token expires (30 days by default), the user will need to re-authenticate through the SAML provider.
- 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.
- ides.config.allowedOrigins
If necessary, provide a list of CORS origins allowed by the IDE Services Server.
- ides.configCustomization.server.forward-headers-strategy
Define how forwarded headers, such as
X-Forwarded-For
, from a reverse proxy are processed in a Spring Boot application. Possible values:NATIVE
: Uses the native web server's support for handling forwarded headers.FRAMEWORK
: Relies on Spring's custom mechanism to process forwarded headers.
For a full list of authentication properties, refer to Values file.
Thanks for your feedback!