OpenID Connect Provider

ActiveManage can act as a sign-in provider for other websites and applications. Rather than your users holding a second set of credentials somewhere else, that other application sends them to you to sign in and receives confirmation of who they are.

This is the opposite of the Single Sign-On section. There, ActiveManage consumes somebody else's sign-in. Here, ActiveManage is the sign-in source.

What you can use it for

• Adding "Sign in with your account" to a companion website, mobile app or intranet tool.
• Letting your own front-end applications authenticate against the platform.
• Giving a background integration its own credentials.
• Sign-in on devices with no keyboard, such as televisions.

Where to find it

Architect Panel → Integration & Connections → OpenID Connect Provider. Users see their side of it on the Connected applications card on their own account page.

Is this what you need?

It is a substantial feature with real security consequences, so it is worth checking it is the right tool:

• To let another application sign users in as your users — yes, this is it.
• To let another system read or write data with no user involved — look at API Clients and API Server first; they are simpler.
• To let your users sign in with an account they hold elsewhere — that is Single Sign-On, not this.

Worked Examples

• Customer portal plus a mobile app: one account, one sign-in, across both.
• Partner integration: a partner's system signs your shared users in without holding their passwords.
• Internal tooling: several small internal tools all authenticating against the main platform.

The feature is off when supplied. Turn it on with Enable OpenID Connect Provider; while it is off, ActiveManage behaves as though the feature does not exist rather than advertising a disabled service.

The settings

• Allow Authorization Code Grant (on) — the standard browser sign-in flow, which is what nearly every application uses.
• Allow Refresh Token Grant (on) — lets an application keep a user signed in without asking again.
• Allow Client Credentials Grant (off) — machine-to-machine access with no user involved.
• Allow Device Code Grant (off) — sign-in for devices with no keyboard.
• Require PKCE (on) — an extra protection on the sign-in exchange. Leave this on.
• Allow "plain" PKCE Method (off) — a weaker form for old applications. Leave off.
• Log OIDC Requests (on) — records every sign-in and token request. Credentials are never logged.

Leave the two "off" grants off

Client credentials and device code are disabled deliberately. Client-credentials access has no user behind it, so nothing about it is limited by a person's permissions. The device grant has the largest attack surface of the four. Enable each only when you have an application that genuinely needs it.

Before you switch it on

• Your platform must be reachable over HTTPS at a stable address — connected applications are configured against it.
• Decide what information you are willing to release.
• In a multi-tenant installation, connected applications and user consents are not shared between tenants.

Each application that will use ActiveManage for sign-in is registered on the OpenID Connect Provider screen.

How it appears to your users

The name, description and logo are shown on the consent screen when a user is asked to approve the application. Get these right — this is exactly what your users read when deciding whether to trust something. A connected application called "test" with no logo will worry people, and should.

Application type

• Confidential — can keep a secret. A server-based website. Gets its own secret.
• Public — cannot keep a secret. A mobile app, or a website running entirely in the browser.

A secret shipped inside a mobile app or a browser page is not a secret. If the code runs on a device you do not control, it is public. Getting this wrong is the most common serious mistake here.

Return addresses

List every address the application may send users back to. They are matched exactly — a trailing slash or a different port will not match — because a loose match is how sign-ins get hijacked. Add development addresses while building, and remove them before going live.

User identifiers

• Shared — every application sees the same identifier for a user.
• Per-application — each sees a different identifier, so two applications cannot compare notes about who your users are.

Prefer per-application unless an application genuinely needs to be matched up with another.

Trusted applications

An application can be marked trusted, which skips the consent screen entirely. Reserve this for applications you publish yourself. It is not appropriate for anything from a third party.

Worked Examples

• Your own mobile app: public client, PKCE required, marked trusted so users are not asked to consent to your own app.
• Partner web application: confidential client, not trusted, limited to the information they actually need.

What a connected application may learn about a user is controlled by a set of permissions, each shown to the user in plain language when they are asked to approve it.

The permissions

• Sign you in — "Verify your identity". Enabled by default.
• Your basic profile — "View your name, username and profile picture". Enabled.
• Your email address — "View your email address". Enabled.
• Your phone number — "View your mobile number". Disabled by default.
• Stay signed in — "Remain signed in without being asked again". Disabled.
• Your security groups — "View which security groups you belong to". Disabled.

The three disabled by default release more than an application usually needs. Enable them deliberately, and per application.

Be careful with security groups

Releasing group membership tells an application a great deal about your internal structure and about the individual. Enable it only where the application genuinely makes decisions from it, and only for applications you control.

Consent

Consent is recorded per user, per application, and it is the thing that gets revoked when access is withdrawn — so it matters more than it looks.

It expires after a set period, one year by default, after which the user is asked again. An application asking for something beyond what the user already approved prompts them afresh, so an application cannot quietly widen its access.

The consent screen is your users' only defence

What they see is the application's name, logo and description together with those plain-language descriptions. That is the entire basis on which they decide. Keep the details honest, and do not mark third-party applications as trusted.

There are four ways an application can obtain access. You choose which are permitted, both site-wide and per application.

Standard browser sign-in

The user is sent to ActiveManage, signs in, approves the application, and is sent back. This is what nearly every application should use, and it is enabled by default.

Leave Require PKCE on. It ties the exchange to the application that started it, so an intercepted sign-in is useless to anybody else. Leave "plain" PKCE off — it provides no real protection and exists only for legacy applications.

Staying signed in

Lets an application keep a user signed in without sending them through sign-in each time.

The credential is replaced every time it is used, and an attempt to reuse an old one is treated as evidence of theft — the whole chain is cancelled immediately. This has one practical consequence worth telling developers: an application must always store the newest credential it receives. One that keeps re-sending its original will find itself signed out.

Machine-to-machine

The application authenticates as itself, with no user involved, so nothing is limited by anybody's permissions. Use it only for a trusted server-to-server integration, and only with a confidential application. Off by default.

Devices with no keyboard

For a television, set-top box or command-line tool. The device shows a short code; the user types it on their phone to approve it. Because that code is short enough for a human to type, this is the most exposed grant — protected by a ten-minute expiry and an attempt limit. Off by default.

The defaults are sensible. Change them only with a reason.

How long things last

• Access — 1 hour.
• Identity assertion — 5 minutes.
• Sign-in code — 60 seconds.
• Stay-signed-in, idle — 30 days; absolute — 90 days.
• Device code — 10 minutes.
• Consent — 1 year, or never if set to zero.

All can be set per application. If you lengthen the access lifetime, understand that you are lengthening the period in which stolen access remains usable.

Signing keys rotate automatically

ActiveManage signs its identity assertions with a key that rotates every 90 days by default. A retired key stays published until everything signed with it has expired, so rotation never breaks anything in flight.

Tell developers to fetch your signing keys from the address ActiveManage publishes them at, rather than copying a key into their configuration. An application with a key hard-coded will break at the first rotation — usually three months after it was built, which is a difficult problem to diagnose.

Four ways access is withdrawn

1. The user disconnects the application from their account page. This is the route to point users at.
2. The application signs the user out and gives up its access.
3. You disable the application. It can obtain nothing new, though access it already holds remains usable until it expires.
4. Theft is detected and the chain is cancelled automatically.

If an application is compromised

Disable it, revoke its consents, and rotate its secret — in that order. Have this written down before you need it.

Two features exist to keep a misbehaving integration from becoming your problem, and to tell you which one is misbehaving.

Rate limiting

Two settings limit how hard a single application may fail: how many failed requests are allowed (20 by default) within a rolling window (10 minutes). Exceeding it blocks that application temporarily.

This is deliberately separate from site-wide login IP blocking. A misbehaving integration should be throttled as an application, not have its server's IP address blocked for every user behind it.

The request log

With logging on — the default — every sign-in and token request is recorded with its decision. Credentials are never recorded. This is where you look to answer: why is an application's sign-in failing, which application is generating failures, and did the user actually reach the consent screen.

The five common integration problems

1. The return address does not match. Matching is exact — a trailing slash, http instead of https, or a different port all fail. By far the most common.
2. PKCE is missing. A public application must use it.
3. The application is asking for something it is not allowed.
4. The grant is not enabled — check both site-wide and per-application settings.
5. Signature checks failing at the far end — almost always an application with a signing key copied into its configuration, after a rotation.

Housekeeping

The request log grows with traffic. Include it in whatever routine you already run over the other logs.