Arcentry Enterprise - Single Sign On (SSO) and Identity Provider Integration
Arcentry Enterprise is the commercial on-premise version of Arcentry. You can learn more about it here or contact us at info@arcentry.com.
Arcentry Enterprise provides an HTTP Webhook that makes it possible to integrate with any Single Sign On System (SSO), existing user database, or third-party identity provider.
How it works
You run an HTTP Server that can connect to your active directory, user database, or other authentication mechanism. Arcentry will make a HTTP POST request to a specified endpoint on that server whenever a user tries to access the app or open a document. Within Arcentry's configuration file, you can specify the URL of your webhooks as well as whether to prompt the user for a login.
Should I show a login form to my user?
It depends. Many Single Sign On solutions rely on a system-wide session that's established whenever a user unlocks their computer. If you are using such a system, set showSignupForm and showLoginForm to false and use the cookie or HTTP-Header set by your SSO to authenticate the user.
Should I show a registration form to my user?
Usually not. For most SSO solutions we recommend disabling signup and password reset by setting showSignupForm and canResetPassword in arcentry-conf.yml to false.
Enabling Webhook Authentication
To switch from the internal user management to a webhook based approach, open arcentry-conf.yml, and change
# Authentication
authType: internal # can be internal or webhook
authWebhook: null # the URL of an HTTP Endpoint that can validate users
documentAccessWebhook: null # the URL of an HTTP authenticate doc access (set to null to disable).
embedAccessWebhook: null # endpoint that verifies access to embeds
authSecret: null # a string that will be included in each request to ensure it comes from the Arcentry server
showSignupForm: true
showLoginForm: true
canResetPassword: true
to
# Authentication
authType: webhook # can be internal or webhook
authWebhook: http://localhost:6066/authenticate-user # the URL of an HTTP Endpoint that can validate users
documentAccessWebhook: http://localhost:6066/authenticate-doc # the URL of an HTTP authenticate doc access (set to null to disable).
embedAccessWebhook: http://localhost:6066/authenticate-embed
authSecret: "7Dm*VqXkx8oi2c0N!IS" # a string that will be included in each request to ensure it comes from the Arcentry server
showSignupForm: false
showLoginForm: true
canResetPassword: false
wherein authWebhook is the URL of a server that you run.
Authenticating Users via Webhook
Arcentry Enterprise will make a HTTP POST request to that server every time a user signs up or logs in with the following payload:
Authenticate User (this is sent to the URL for authWebhook)
{
// These are the credentials the user entered into the login form
"credentials": {
"email": "some-email@domain.com",
"password": "sesame"
},
// These are the headers sent with the original request.
// This is particularly useful if your SSO solution sets cookies in the browser
"headers": {
"accept": "application/json",
"user-agent": "Needle/2.2.4 (Node.js v10.15.1; win32 x64)",
"content-length": "48",
"content-type": "application/json; charset=utf-8",
"host": "localhost:8060",
"connection": "close"
},
// A random String that can be set in arcentry-conf.yml
// It helps you verify that this request was indeed sent by
// the Arcentry Enterprise Server
"authSecret": "some-string"
}
Your server should now validate the user's login attempt and either reply with an HTTP Status 200 if the authentication attempt is valid or any other status code (usually 403) if not.
For successful authentications, your server's response-body should be a single string that uniquely identifies the user, e.g. a user-id, or an email.
For unsuccessful attempts, you can return either an empty body or an error message string for Arcentry to display to the user.
Authenticating Document Access
Once the user is authenticated to access the app in general, your server can decide for every document or embed if the user is permissioned to access it.
To activate this feature, specify a URL for documentAccessWebhook in arcentry-conf.yml. Arcentry will contact this URL every time a user tries to open a document with the following payload:
Authenticate Document Access (this is sent to the URL for documentAccessWebhook)
{
"user": {
"email": "user-a@test.com",
// Arcentry's internal ID for that user
"id": "d1516677-2359-42e6-8bcd-701cebb3616b",
// This is the string you've provided as a response to the authenticate user call,
// usually the internal id or email for that user
"thirdPartyId": "user-a-id"
},
// The headers sent with the user's request. Please note, the cookie String
// often contains both the cookies set by your SSO system as well as Arcentry's sessionId
"requestHeaders": {
"accept": "application/json",
"user-agent": "Needle/2.2.4 (Node.js v10.15.1; win32 x64)",
"cookie": "sessionId=c1469063-55e5-462c-a19d-11cb4eaf3af6;",
"host": "localhost:8060",
"connection": "close"
},
// The auth secret string you've specified in arcentry-conf.yml
"authSecret": "abcdef",
// The id of the document the user wishes to access
"docId": "3e543c40-d391-40eb-81e6-8a9974048887",
// The following flags allow you to distuinguish between access requests for documents
// and embeds if used with the same webhook URL.
"isDoc": true,
"isStaticEmbed": false,
"isLiveEmbed": false
}
Authenticating Embed Access
Authenticating Access to Static and Live Embeds are both handled by the embedAccessWebhook in arcentry-conf.yml. The payloads are as follows:
Authenticate Access to Static Embeds (this is sent to the URL for embedAccessWebhook)
{
// Embeds often show diagrams for users without Arcentry accounts.
// In this case, user.email and user.id are null
"user": {
"email": null,
"id": null
},
"requestHeaders": {
"accept": "application/json",
"user-agent": "Needle/2.2.4 (Node.js v10.15.1; win32 x64)",
"cookie": "sessionId=506003fa-696c-4cee-bd51-a027c17da802;",
"host": "localhost:8060",
"connection": "close"
},
"authSecret": "abcdef",
// The ID of the static embed the user is trying to access
"embedId": "6d1ec437-e50c-4731-9bc0-5a2cc20f2a9f",
// The ID of the underlying document this embed is based on
"originalDocId": "ded701a9-5036-4ba7-8ead-7b156824ca44"
"isStaticEmbed": true,
"isLiveEmbed": false,
"isDoc": false,
}
Authenticate Access to Live Embeds (this is sent to the URL for embedAccessWebhook)
{
"user": {
"email": null,
"id": null
},
"requestHeaders": {
"accept": "application/json",
"user-agent": "Needle/2.2.4 (Node.js v10.15.1; win32 x64)",
"cookie": "sessionId=506003fa-696c-4cee-bd51-a027c17da802;",
"host": "localhost:8060",
"connection": "close"
},
"authSecret": "abcdef",
"docId": "ded701a9-5036-4ba7-8ead-7b156824ca44",
"isDoc": false,
"isStaticEmbed": false,
"isLiveEmbed": true
}