Set up single sign-on

Besides GitHub, Google, Microsoft and Apple, people can sign in to Peerlify through your own OpenID Connect (OIDC) identity provider. You register it once, for your email domain. After that, anyone who types an address at that domain on the sign-in page is sent to your provider.

What you need

• An email address at the domain, for example ana@example.com.
• Control over the web server at that domain, to publish a file at https://example.com/.well-known/webfinger.
• An OIDC provider that:
  • publishes /.well-known/openid-configuration over HTTPS, and
  • accepts Dynamic Client Registration (RFC 7591) without credentials, at a registration_endpoint on the same host as the issuer. If yours doesn't, see Providers without dynamic registration.
  • is reachable from the internet: its issuer must resolve to public IP addresses and serve its configuration without a redirect.

No Peerlify account or plan is required to register.

1. Publish a WebFinger record

Serve this JSON from https://<your domain>/.well-known/webfinger. A static file returning the same document for every request is fine:

{
  "subject": "acct:ana@example.com",
  "links": [
    {
      "rel": "http://openid.net/specs/connect/1.0/issuer",
      "href": "https://login.example.com"
    }
  ]
}

href is your provider's issuer URL: the issuer value in its openid-configuration.

Peerlify checks that:

• the record is served over HTTPS directly on the email domain, with a 2xx status and no redirect, and the domain resolves to public IP addresses;
• the response is JSON with a links entry whose rel is http://openid.net/specs/connect/1.0/issuer;
• href is an absolute https URL without a query or fragment.

Test it:

curl -s "https://example.com/.well-known/webfinger?resource=acct:ana@example.com&rel=http://openid.net/specs/connect/1.0/issuer"

2. Register the domain

1. Open https://login.peerlify.com/register.
2. Under Enterprise, choose Set up SSO for your company (OIDC).
3. Enter your Work email. The form shows the WebFinger address it will read.
4. Click Register provider.

Peerlify reads your WebFinger record, finds your provider, registers itself there as a client named Peerlify, and shows OIDC provider registered.

A domain can have only one single sign-on registration. If someone already registered single sign-on for it, registration fails with The domain '<domain>' is already registered to a network. Other networks never block registration, including a network created for the domain by earlier Microsoft sign-ins, or one your Microsoft Entra tenant has taken over (see How you get networks); that network stays as it is, with its members, and the sign-in page sends addresses at the domain to your provider.

There is currently no way to view, change or remove a registered provider in the console. Contact Peerlify support for changes.

3. Sign in

On https://login.peerlify.com, type an address at your domain in Work email. The page shows Your organization uses name with a Continue with button. The match is exact: an address at eu.example.com doesn't match a registration for example.com.

Peerlify signs people in with authorization code and PKCE, requesting the scopes openid profile email, and uses the email from your provider.

If registration fails

Registration is limited to 5 attempts per minute from one IP address.

Providers without dynamic registration

Some providers don't allow anonymous client registration. For those, register a client yourself and give Peerlify its credentials:

1. In your provider, create a confidential web client using the authorization code flow, with the redirect URI https://login.peerlify.com/signin-oidc-<domain>, where <domain> is your email domain in lowercase, with each run of characters other than letters and digits replaced by a single -. For example.com, that's https://login.peerlify.com/signin-oidc-example-com. If another registered domain already produced the same name (for example a.b-c.com and a-b.c.com both give a-b-c-com), Peerlify adds - and the first 6 hex digits of the SHA-256 of your lowercase domain. The registration response's scheme field always has the final name; the redirect URI is https://login.peerlify.com/signin-<scheme>.

2. Publish the WebFinger record as in step 1.

3. Register with the client's credentials. This option is available through the API only:

   shell

   curl -X POST https://login.peerlify.com/api/account/register-oidc-provider \
     -H "Content-Type: application/json" \
     -d '{"email":"ana@example.com","clientId":"<client id>","clientSecret":"<client secret>"}'

   Copy

   A successful response is {"success": true, …}. The WebFinger record still decides which issuer is used.

Provisioning from Okta

If your provider is Okta, it can also add and remove members and sync groups for access rules, on the Enterprise plan. See User and group provisioning.

Next steps

• Sign-in and sessions
• Invite people