Authentik IdP

Introduction

Single Sign-on (SSO) is a technology that allows users to sign in only once and then get access to multiple applications/services without re-authentication.

If a web portal includes several large independent sections (forum, chat, blogs, etc.), a user can undergo the authentication procedure within one of the services and automatically get access to all other services without entering credentials several times.

SSO is always ensured by the joint operation of two applications: an Identity Provider and a Service Provider (also called "IdP" and "SP"). ONLYOFFICE SSO implements the SP only. A lot of different providers can act as an IdP, but this article considers the Authentik implementation.

Creating an IdP in Authentik

1. Sign in to the Authentik admin panel (https://authentik.yourdomain.com/if/admin/).

2. Go to Customization -> Property Mappings.

3. Click Create -> SAML Provider Property Mapping.

4. In this way, create 3 Property Mappings with the following parameters:

   Name	SAML Attribute Name	Expression
   SAML givenName Mapping	givenName	return user.attributes["first_name"]
   SAML sn Mapping	sn	return user.attributes["last_name"]
   SAML mail Mapping	mail	return user.email

   This property mapping must be configured if users have attributes specified in Authentik. If the attributes are different, replace them with the necessary ones; if there are no attributes, no configuration is needed.

   

5. Go to Providers -> Create.

6. Select the SAML type.

   

7. Fill in the following fields:

   Name	Apps SAML
   Authorization flow	default-provider-authorization-implicit-consent (Authorize Application)
   ACS URL	https://docspace.example.com/sso/acs
   Issuer	https://docspace.example.com/sso/metadata
   Service Provider Binding	POST
   Sign assertions	true
   Sign responses	true
   Signing Certificate	For the first time, you can specify authentik Self-signed Certificate or replace it with your own certificate
   Property mappings	If you configured attributes in step 4, you need to add them from the left column to the right one by selecting and clicking the right arrow

   

   

8. Click Finish.

9. Go to Applications -> Create.

10. Fill in the following fields:

    Name	Apps SAML
    Slug	docspace
    Provider	Select Docspace SAML
    Policy engine mode	any

11. Click Create.

    

12. Go to the created SAML Provider.

13. Find the Metadata URL link (usually it is https://authentik.example.com/application/saml/docspace/metadata.xml)

14. Copy this link or download the XML.

    

Configuring ONLYOFFICE SP

Make sure that you are signed in as an Administrator to your ONLYOFFICE Apps workspace and go to the Settings menu, select the Integration section, and open the Single Sign-On tab.

1. Enable SSO using the Enable Single Sign-on Authentication switch and paste the copied link into the URL to Idp Metadata XML field.

2. Press the button with the upward arrow to load the IdP metadata. The ONLYOFFICE SP Settings form will be automatically filled in with your data from the Authentik IdP.

3. If users do not have attributes configured and step 4 of the Creating an IdP in Authentik section was not performed, then the following parameters must be specified in Attribute Mapping:

   First Name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
   Last Name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
   Email	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

   

4. Create a certificate in the SP Certificates section. To do that, click the Add certificate button in the corresponding section.

   

5. In the opened modal window, click the Generate New Self-Signed Certificate link, and choose the Signing and encryption option in the Use for list. Before you save the certificate, copy the Public Certificate text to the clipboard and save it in a file (it will be necessary for Authentik), then click the OK button.

   

   

6. Click the Save button.

7. The ONLYOFFICE SP Metadata section with the Download SP Metadata XML button should be opened.

   

8. Return to Authentik to add the copied certificate. Go to System -> Certificates -> Create.

9. Type in an arbitrary name and paste the copied certificate.

   

10. Specify this certificate in the provider settings.

    

    If encryption is required, then in step 8 you need to create a certificate with a private key, and specify this certificate in the Encryption Certificate field.

Checking the work of the ONLYOFFICE SP with the Authentik IdP

1. Go to the ONLYOFFICE Apps Authentication page (e.g., https://myportal-address.com/login).

   

2. Click the Single Sign-on button. If the button is missing, this means that SSO is not enabled.

3. If all the SP and IdP parameters are set correctly, you will be redirected to the Authentik IdP login form.

4. Enter the login and password of the Authentik user and click the Sign In button.

5. If the credentials are correct, you will be redirected to the main page of the workspace (the user will be created automatically if missing, or the data will be updated if changed in the IdP).