SAML with Okta
Below is an example of how to configure dotCMS to authenticate and authorize dotCMS users with Okta using SAML. It requires a number of custom attributes to be set in order to successfully connect, authenticate and also sync roles from Okta to dotCMS.
Example Custom Attributes Required for dotCMS and Okta SAML#
Below are a list of custom attributes from a working Okta installation. The value containing "ClientDomain" should obviously be replaced with correct values for the Okta endpoint and the dotCMS server location. If you are cutting and pasting, please make sure not to include leading or trailing spaces in the values.
| Key | Value |
|---|---|
attribute.email.name | email@address.com |
attribute.firstname.name | firstName |
attribute.lastname.name | lastName |
logout.okta.url | https://clientDomain.okta.com/login/signout |
logout.protocol.binding | Http-Okta |
logout.service.endpoint.url | https://clientDomain.com/dotAdmin/show-logout |
nameidpolicy.format | urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified |
protocol.binding | urn:oasis:names:tc:SAML:2.0:bindings:HTTP-REDIRECT |
remove.roles.prefix | iam_dotcms_ |
renew.session | false |
verify.signature.credentials | false |
Special Property Notes#
logout.protocol.binding#
The value Http-Okta is a dotCMS-specific binding mode, not a standard SAML binding. It is required for Okta because Okta uses a dedicated signout URL for logout rather than the logout endpoint described in its IdP metadata XML.
When this binding is set, dotCMS uses the URL specified in logout.okta.url to perform logout, instead of deriving the logout destination from the IdP metadata.
No other IdP should use this value.
verify.signature.credentials#
The example configuration sets verify.signature.credentials to false. This disables verification of the cryptographic signature on the SAML response from Okta. While some Okta configurations require this, you should confirm with your Okta administrator whether signature verification can be enabled.
Leaving signature verification disabled reduces the security guarantees of the SAML integration and should be treated as a configuration to revisit rather than a permanent setting.
remove.roles.prefix#
In the example above, remove.roles.prefix is set to iam_dotcms_. This means that if Okta returns a role named iam_dotcms_editor, dotCMS will strip the prefix and register the role as editor when synchronizing the user's roles. The prefix convention shown here is illustrative; your Okta configuration may use a different prefix, or none at all.
Example IDP Metadata file#
A redacted example metadata file for Okta:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/clientIdNumber"> <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:KeyDescriptor use="signing"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:X509Data> <ds:X509Certificate>XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==</ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </md:KeyDescriptor> <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://clientDomain.okta.com/app/clientDomain_appId_1/clientIdNumber/slo/saml"/> <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://clientDomain.okta.com/app/clientDomain_appId_1/clientIdNumber/slo/saml"/> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat> <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://clientDomain.okta.com/app/clientDomain_appId_1/clientIdNumber/sso/saml"/> <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://clientDomain.okta.com/app/clientDomain_appId_1/clientIdNumber/sso/saml"/> </md:IDPSSODescriptor> </md:EntityDescriptor>