DDM HelpOkta
With Okta, your people sign in to DDM through your Okta sign-in page – with your Okta policies and MFA. You create an app integration in Okta and enter it in DDM under Settings › Single sign-on.
You need an Okta administrator who may create app integrations (Super Administrator or Application Administrator).
1. Create the app integration
New integration
In the Okta Admin Console, go to Applications › Applications › Create App Integration. Choose OIDC – OpenID Connect and Web Application, then Next.
General settings
- App integration name:
DDM - Grant type: Authorization Code (preselected)
- Sign-in redirect URIs: the Redirect URI from DDM, Settings › Single sign-on – e.g.
https://cms.documentdistributionmanager.com/api/auth/sso/callback - Sign-out redirect URIs: leave empty
Assignments
Under Controlled access, choose who may use DDM – everybody in your organisation, or selected groups. You can change it later under the app's Assignments tab.
Save
Click Save. On the app's General tab, copy the Client ID and the Client secret.
2. Enter it in DDM
Under Settings › Single sign-on › Identity provider:
| Field | Value |
|---|---|
| Button label | e.g. Okta or your company's name |
| Issuer | https://<your org>.okta.com – the address of your Okta, without -admin |
| Client ID | from Okta |
| Client secret | from Okta |
| E-mail claim | email |
Click Save, then Test connection, and switch on Single sign-on active – see Single sign-on.
https://<your org>.okta.com/oauth2/default. Both work; the issuer is shown on the authorisation server's settings page.Map groups
To have DDM put people into groups by their Okta groups:
- In Okta, open the app's Sign On tab and, under OpenID Connect ID Token, click Edit.
- Set Groups claim type to Filter, the claim name to
groups, and a filter – e.g. Matches regex.*for all groups, or Starts withDDM-for only those meant for DDM. Save. - In DDM, under Groups, enter
groupsas the Group claim and add a mapping for each group: the name of the Okta group and the DDM group.
…/oauth2/default), the groups claim is set up there instead – under Security › API › the server › Claims › Add Claim, name groups, include in the ID Token, value type Groups. If you limit it to a scope, enter that scope (e.g. groups) under Scopes in DDM.With SAML instead
- Under Settings › Single sign-on, add a provider with Okta and SAML 2.0. DDM shows three values for it.
- In Okta, go to Applications › Applications › Create App Integration › SAML 2.0, name it
DDM. - Under Configure SAML, enter DDM's Reply URL (ACS URL) as the Single sign-on URL and DDM's Identifier (Entity ID) as the Audience URI (SP Entity ID). Name ID format:
EmailAddress, Application username:Email. - Under Attribute Statements, add
email→user.email,firstName→user.firstName,lastName→user.lastName. For groups, add a Group Attribute Statement namedgroupswith a filter, as above – and entergroupsas the Group claim in DDM. - After saving, copy the Metadata URL from the app's Sign On tab and enter it in DDM under Your provider's metadata › Metadata URL. Save.
- Assign people or groups under Assignments.
Common errors
| Message | Cause | Solution |
|---|---|---|
400 Bad Request – The 'redirect_uri' parameter must be a Login redirect URI | The redirect URI in Okta differs from the one DDM shows | Copy it from DDM again. |
| User is not assigned to the client application | The person is not assigned to the app | Assign them or their group under Assignments. |
| There is no discovery document under this issuer (in DDM, on saving) | The issuer contains -admin, or a path that does not exist | Use https://<your org>.okta.com. |
| The provider rejected the client ID or the secret | Copied incompletely, or the secret was rotated | Copy both again from the General tab. |
| Your e-mail address is not on one of your organisation's confirmed domains | The person's Primary email in Okta is on another domain | Correct it in Okta, or confirm the domain in DDM. |
Alternatively: Okta's LDAP interface
Okta can also present its users as an LDAP directory. Connected as a directory service, DDM imports your people from Okta in advance, sorts them into groups by their Okta groups and blocks people who are deactivated – but they then type their Okta password into DDM's sign-in page, without Okta's MFA.
The two can be combined: the directory service imports and sorts people, single sign-on signs them in.
| Field | Value |
|---|---|
| Host | <your org>.ldap.okta.com |
| Port / Require TLS | 636 / on |
| Base DN | dc=<your org>,dc=okta,dc=com |
| Bind DN | a read-only administrator, e.g. uid=svc-ddm@company.com,dc=<your org>,dc=okta,dc=com – Okta shows the exact format on the LDAP interface page |
| Search base DN of the query | ou=users,dc=<your org>,dc=okta,dc=com |
| Search filter | (&(objectClass=inetOrgPerson)(mail=*)) |
Switch the interface on in Okta under Directory › Directory Integrations › Add LDAP Interface, and check in the preview whether your Okta groups appear under memberOf.
Okta sign-in for the whole installation
Whoever runs a DDM installation can also offer Sign in with Okta to every organisation on it – with one Okta app for all of them, set up on the server: OKTA_CLIENT_ID, OKTA_CLIENT_SECRET and OKTA_ISSUER (e.g. https://company.okta.com), redirect URI <BETTER_AUTH_URL>/api/auth/callback/okta. The button appears once all three are set. Like the Microsoft and Google sign-in for the whole installation, it creates no memberships and is the same for everybody; it suits a dedicated installation for one company. An organisation that wants its own Okta, its own rules or group mapping uses single sign-on as described above.