Connect DocuWare with Okta

Connect DocuWare with Okta

The following configuration guide uses Okta as an example to show how to connect your DocuWare organization to a generic identity provider to use single sign-on in DocuWare.

The essential steps are similar with other identity providers, although they might differ in detail.

1. Activate single sign-on in DocuWare

Select DocuWare Configuration > Organization settings > Security > Enable single sign-on with your identity provider.

Click on Configure single sign-on connection.

In the new dialog choose as Identity Provider the option Generic OpenID Connect Identity Provider.

Several fields for configuration are shown then – see the screenshot below. The entries for these fields (except for Callback URL) you can copy later from your Okta platform after you have created an application and an Authorization Server to connect Okta to Docuware.

2. Create in Okta an application for DocuWare

Switch to your Okta platform and create a new app that bundles the settings for connecting to DocuWare:

Okta > Applications > Create App Integration

Select OIDC – OpenID Connect as Sign-in method and Web Application as Application type:

Press Next to go to General Settings.

Give the app a name, e.g. DocuWare. You can enter what you want. The name is only visible in the Okta platform.

Activate in the General Settings also the Grant type: Client Credentials and copy from DocuWare the Callback URL to the Sign-in Redirect URIs line.

You can find the callback URL in the dialog Configure single sign-on connection in DocuWare Organisation Settings (see also item 1).

Now select the desired access type under Assignments and save the new app:

3. Create in Okta an Authorization Server for DocuWare

Go to Okta > Security > API > Authorization Servers > Add Authorization Server:

Enter a name for the Authorization Server. In the Audience field, enter api://docuware as shown.

Then, the new Authorization Server is listed in the API section of Okta:

4. Enter Issuer URL in DocuWare

In the Authorization Server settings, you can find the Metadata URI. This is the URL that DocuWare can use to call Okta as an identity provider. It is located here:

Okta > Security > API > Authorization Servers > Your Authorization Server for DocuWare > Settings > Metadata URI.

Copy the Metadata URI and enter it into the field Issuer URL in DocuWare:

5. Copy Client ID und Client Secret from Okta to DocuWare

In the settings of the app you created in step 2, you can find the Client ID and generate the Client Secret. These are identifiers that the apps can use to identify each other.

Go to Okta > Applications > Your application for DocuWare > General.

You enter the Client ID and Client Secret in the Client ID and Client Secret Key fields in DocuWare.

6. Add an Access Policy in Okta

In Okta, you use the Access Policy to connect the Authorization Server and the app you created for DocuWare.

Go to Okta > Security > API > Authorization Servers > Your Authentication Server for DocuWare > Access Policies > Add Policy.

Enter a name and a description.

Under Assign to, select the application you created for DocuWare in step 2 and create the policy.

Now create a new rule for the policy with the button Add Rule.

Enter the following settings for the rule (recommended):

Grant type > Client acting on behalf of itself > Client Credentials
Grant type > Client acting on behalf of a user > Authorization Code
Grant type > Client acting on behalf of a user > Implicit (hybrid)
Grant type > Client acting on behalf of a user > Resource Owner password
Grant type > Client acting on behalf of a user > SAML 2.0 Assertion
Grant type > Client acting on behalf of a user > Device Authorization
Grant type > Client acting on behalf of a user > Token Exchange
 AND
User is: Any user assigned the app
 AND
Scopes requested: Any scopes

THEN
Use this inline hook: None(disabled)
 AND
Access token lifetime is 1 Hour
 AND
Refresh token lifetime is: Unlimited but will expire if not used every 7 Days

7. Define and assign attributes

In order for DocuWare users to be assigned to identities stored in Okta, you first define the properties for the identities in Okta and then enter these properties in DocuWare.

Note: the properties of the identities are called "attributes" in DocuWare and "claims" in Okta.

DocuWare requires four attributes for mapping:

  • Email

  • Username

  • External ID

  • ID of the external provider

The attributes are entered in DocuWare in the Configure Single Sign-On Connection dialog (see step 1):

To define the properties in Okta, open the Authorization Server you created for DocuWare in Okta:
Okta > Security > API > Authorization Servers > Authorization Server for DocuWare.

Press Add Claim.

Create a claim for the attribute „Email“

The name - here "dw_mail" is freely selectable. But you have to copy the name in DocuWare exactly as it is here.

The value "user.email" is predefined by Okta and must be entered here exactly as shown here.

  • Include in token type: ID Token / Always

  • Value Type: Expression

  • Value: user.email

  • Disable claim: none

  • Include in: Any scope

Create a claim for the attribute „Username“.

The name - here "dw_username" is freely selectable. But you have to copy the name in DocuWare exactly as it is here.

The value "user.username" is predefined by Okta and must be entered here exactly as shown here.

  • Include in token type: ID Token / Always

  • Value Type: Expression

  • Value: user.username

  • Disable claim: none

  • Include in: Any scope

Create a claim for the attribute „External ID“.

The external ID is the unique number of the user in Okta. The name - here "dw_externalid" is freely selectable. But you have to copy the name in DocuWare exactly as it is here.

The value "user.id" is predefined by Okta and must be entered here exactly as shown here.

  • Include in token type: ID Token / Always

  • Value Type: Expression

  • Value: user.id

  • Disable claim: none

  • Include in: Any scope

For the identities to be transferred to DocuWare, make sure that the External ID attribute is really assigned to user.id.

Create a claim for the attribute „External Provider“.

The name for this claim - here "dw_provider" is freely selectable. But you have to copy the name in DocuWare exactly as it is here.

You can find the ID in the overview of the Authorization Servers, as it is shown here on the screenshot below. Make sure you enter the chars with quotation marks.

Enter this value in the value line with quotes.

  • Include in token type: ID Token / Always

  • Value Type: Expression

  • Value: “xxxxxxxxxx”

  • Disable claim: none

  • Include in: Any scope

In this configuration example, the following claims are entered as attributes in DocuWare:

Assign user to the application

The users who should be able to log in to DocuWare with single sign-on must be assigned to the DocuWare application in Okta.

To do this, go to the application for DocuWare in Okta: Applications > Application X (DocuWare). Switch to Assignments.

When assigning a user, make sure that the User Name field is filled in with their email address.

Now the configuration of connecting DocuWare with the external identity provider Okta is finished and you can start using single-sign-on.