Note:
Due to the technical content, many terms and commands in this article are in English.
Basics
In this guide, we’ll show you how to set up single sign-on (SSO) with SAML or OpenID in COYO. To configure an authentication provider for COYO, you first need to configure an identity provider (IDP).Note:
Please note that we are unable to provide assistance for configuring an IDP as there are many different providers on the market.
Please note that we are unable to provide assistance for configuring an IDP as there are many different providers on the market.
COYO authentication providers
COYO makes it possible to set up several authentication providers and supports the protocols SAML2.0 and OpenID. We support all IDPs that use these two common authentication protocols. This makes it possible to automatically authenticate yourself using the Windows-integrated authentication (SAML) or on networks, such as LinkedIn (OpenID).
Using SAML just-in-time, users can be imported during the first login if they don’t yet exist in COYO.
Using SAML just-in-time, users can be imported during the first login if they don’t yet exist in COYO.
Note:
COYO does not support 2-factor authentication. You can, however, use a SAML service. You need to ensure that the service uses a certificate from a trustworthy certification body and TLS 1.2.
COYO does not support 2-factor authentication. You can, however, use a SAML service. You need to ensure that the service uses a certificate from a trustworthy certification body and TLS 1.2.
Create an authentication provide
Log into your COYO as an administrator and go into the Administration. When opening the area "Authentication", you’ll see the following:
Click on "Create authentication provider", select the desired "Type" (SAML, OpenID) and add a tick for "active". Select automatic login to set up an automatic redirect to your IDP after 3 seconds.
SAML
To set up SAML, you should find the entity ID, endpoints, certificates, and much more in the metadata.xml of your identity provider (IDP).
If you use Microsoft ADFS, you’ll find the metadata.xml at:
General information
It’s now time to configure your SAML authentication provider. The screenshot shows an example configuration for an ADFS. The following points are important:
- Only activate "ADFS" if your Microsoft Active Directory uses "Federation Services".
- "Entity ID", "Authentication URL" and "Logout URL" are listed in the metadata.xml of your IDP.
- "Logout method" defines whether the user is logged out locally (only COYO) or globally (SAML logout) when they log out of COYO.
- "Response validity" defines the period of time for queries. We recommend the usual 300 seconds.
- "User directory" defines for which users you want to use this authentication provider.
The local COYO endpoints and thus also the metadata XML are generated after activating and saving.
Request signing
Activate this function by selecting "Sign request". It’s possible to sign the SAML request in COYO with a certificate and a private key. Simply add both here and ensure that you use the PEM format. You can use a self-signed certificate. The certificate must then be added to the ADFS server in the trust relationship settings under "Signing".
Response validation
Alongside the signing of COYO requests, it’s also possible to check the response of the SAML server. To do this, you can simply add the token-signing certificate of the IDP server here.
Deactivate to skip the validation.
Just-in-time provisioning (optional)
If you don’t want to use SAML to import users, you can continue with the next step.
From version 25, COYO also offers the option of importing users when first logging in using SAML.
In this case, choose the type SAML just-in-time. On the Just-in-time provisioning tab, you need to define the attributes that are imported for the users. You will get the necessary values if you search for them in your FederationMetadata.xml.
From Cloud release 31, it’s also possible to synchronize profile fields. To do this, choose the profile fields in the JIT provisioning and assign them according to the values in FederationMetadata.xml.
Add trust relationship
Once you’ve finished, you need to add COYO to your IDP. For Microsoft ADFS, this means the management tool ADFS.
COYO only establishes a redirect to the ADFS server and then expects an "SAML assertion", in which the login name (e.g. the e-mail address) is passed on as "Name ID". In ADFS, this is set up under Claim Issuance:
For SAML just-in-time, the attributes that are provisioned must also be configured there:
Note that the outgoing claims have a different name on a German-language server.
If there are errors for the connection with ADFS, this article might provide you with further assistance.
Connection test
You now have a fully configured SAML IDP, which can be used when logging into COYO. The last thing to do is to simply test the login with a user from the user directory you have configured.
Open ID
In contrast to SAML, OpenID authentication is always available to all COYO users once activated and is not limited to one of the COYO user directories. To configure OpenID, please read the OpenID handbooks from the identity provider.
In this article, we’ll show you an example of a configuration for Microsoft 365. The following points are important:
- The "Mapping ID" is the parameter in the IDP response that needs to match the login name of the COYO user.
The "unique_name" should in this case match the e-mail of the COYO user. - To create the "Client ID" and "Client Secret", you need to register COYO as a web application in the Administration of your IDP. You will be asked for the COYO login URL. This redirect URL is generated when saving your configuration for the authentication provider in COYO.
- The URLs for "Authentication", "Access Token", and "User Info" are defined in the app registration of your IDP.
In the screenshot, you can see the entire schema for Microsoft 365 with its Azure tenant. "Scope" are the permissions that you need to access the URL for user information. "Token Schema" and "Authentication schema" are defined by the IDP.
We have also prepared instructions for the integration of Microsoft 365 via Microsoft Azure: Microsoft 365 integration.
Open ID: Other examples
- If you are using e-mail as a login name, you can use the e-mail as a "Mapping ID".
- "Client ID" and "Client Secret" are generated by Facebook and can be configured at https://developers.facebook.com/apps/. Simply add a new app and configure it as a Facebook login.
- "Authentication URL": https://www.facebook.com/dialog/oauth
- "Access Token URL": https://graph.facebook.com/oauth/access_token
- "User Info URL": https://graph.facebook.com/me?fields=email
- "Scope": email
- "Token Schema": query
- "Authentication schema": form
- If you are using e-mail as a login name, you can use the e-mail as a "Mapping ID".
- "Client ID" and "Client Secret" are generated by LinkedIn and can be configured at https://www.linkedin.com/developer/apps. Simply add a new app and configure it as a LinkedIn login.
- "Authentication URL": https://www.linkedin.com/oauth/v2/authorization
- "Access Token URL": https://www.linkedin.com/oauth/v2/accessToken
- "User Info URL": https://api.linkedin.com/v1/people/~:(email-address)?format=json
- "Scope":r_liteprofile,r_emailaddress
- "Token Schema": header
- "Authentication schema": query
Private Microsoft accounts
- If you are using e-mail as a login name, you can use the e-mail as a "Mapping ID".
- "Client ID" and "Client Secret" are generated by Microsoft and can be configured at https://apps.dev.microsoft.com/#/appList. Simply add a new app and configure it as a Microsoft login.
- "Authentication URL": https://login.microsoftonline.com/common/oauth2/v2.0/authorize
- "Access Token URL": https://login.microsoftonline.com/common/oauth2/v2.0/token
- "User Info URL": https://graph.microsoft.com/v1.0/me
- "Scope": openid https://graph.microsoft.com/User.Read
- "Token Schema": header
- "Authentication schema": form
Google Workspace
- If you are using the e-mail as a login name, you can use the e-mail as a "Mapping ID".
- "Client ID" and "Client Secret" are generated by Google and can be configured at https://console.developers.google.com/apis/credentials. Simply add a new app and configure it as a Google login.
- "Authentication URL": https://accounts.google.com/o/oauth2/auth
- "Access Token URL": https://www.googleapis.com/oauth2/v4/token
- "User Info URL": https://www.googleapis.com/oauth2/v3/userinfo
- "Scope"email profile openid
- "Token Schema": header
- "Authentication schema": header
Does a new authentication provider also need to be created for each user directory?
In the case of SAML, yes. When creating an SAML authentication provider in the Administration in COYO, exactly one user directory must be stated and this login only applies to users of this user directory.OpenID, however, applies to all users in your COYO.
