SanctiKey

Documentation

Federation.

Federation connects your existing identity provider to SanctiKey so your people sign in with the credentials and the multi-factor policy you already run. SAML 2.0 and OIDC are both supported, and the console configures either one.

Read this first

A federated user arrives with no permissions.

Single sign-on proves who somebody is. It does not decide what they may do. When a person signs in through your identity provider for the first time, their account is created here with no permission tier and therefore no access. They will reach the console and every action will be refused.

This is deliberate. Nothing your identity provider sends can grant privileges in your key account, so a group name or a role claim from the provider side cannot promote anybody. Access is granted here, by a person, on purpose.

Two steps close the gap:

  1. 1. An administrator opens Admin, Users, selects Groups on the new user, chooses their permission tiers, and saves. See assigning a tier.
  2. 2. The user signs in again. Permissions are fixed into a session at the moment it is issued, so the session they are already holding will not pick up the change. Signing out and back in is what makes the new tier take effect.

The same applies whenever you change a tier, not only on first sign-in. If somebody says a permission change did not work, the first question is whether they signed in again.

Before you start

  • You need the SystemAdministrators tier. Federation is not delegated to any lower tier: it decides who can reach the account, so it sits with the top tier only.
  • One identity provider is configured at a time. Saving again reconfigures the existing one rather than adding a second, and the console button reads Reconfigure once one exists.
  • Your provider must send an email address. It is the identifier a user account is keyed on here, so a provider that omits it produces accounts you cannot manage. Both walkthroughs below name the exact attribute.
  • Keep one administrator who signs in without federation. If the provider becomes unreachable, or a metadata certificate expires, that account is how you get back in.

SAML setup

The console splits this into two steps, because your provider needs values from us before we need values from it. Open Admin, Federation, select Configure IdP, and choose SAML. The panel that appears is step one: the service provider values to paste into your provider.

Step 1: create the application in your identity provider

In Okta, Entra ID, Ping, Auth0 or whatever you run, create a SAML 2.0 application using these values. The console shows the real strings for your account, already filled in and selectable; the shapes are below so you know what you are looking at.

Single sign-on / ACS URL
https://<your-auth-domain>/saml2/idpresponse

Your sign-in domain, shown literally in the console.

Audience URI (SP entity ID)
urn:amazon:cognito-sp:<your-user-pool-id>

Unique to your account.

Email attribute name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

The same for every account. Required.

Then do the step people skip: assign the users or groups who should have access to that application. Nobody can sign in through a provider application they are not assigned to. This assignment controls who can reach SanctiKey at all; it does not control what they can do once they arrive.

Finish by copying the application’s metadata URL.

Step 2: save it here

Back in the Federation tab, fill in the form and select Save Configuration:

Protocol
SAML
Provider Name
A short label such as Okta. Letters, digits, underscores and hyphens only. Your people will see it on the sign-in page.
Metadata URL
The metadata URL you copied in step one.

Saving creates the provider and enables it on the sign-in application in one action, so there is no second switch to remember. The Federation tab then shows the provider name, the protocol, the status, and the service provider values again for reference.

OIDC setup

Same two steps, different values. Select Configure IdP and choose OIDC.

Step 1: create the application in your identity provider

Create a web application, confidential rather than public, using the authorization code grant. A public or single-page application type will not work: the exchange is done server to server with a client secret.

Sign-in redirect URI
https://<your-auth-domain>/oauth2/idpresponse

Your sign-in domain, shown literally in the console.

Grant type
Authorization Code
Scopes your application must allow
openid email profile
Email claim
email

Required.

Assign your users or groups to the application, then copy its client ID, client secret, and issuer URL.

Step 2: save it here

Protocol
OIDC
Provider Name
A short label. Letters, digits, underscores and hyphens only.
Client ID
From the application you just created.
Client Secret
Written straight into a secrets vault. It is never stored in our database, never written to a log, and never returned by any API response, including the one that reads your federation configuration back.
Issuer URL
The provider base URL, for example https://your-idp.example.com. Discovery metadata is read from it.

The first sign-in

Have one person sign in through the provider before you tell everybody. The sequence you should expect:

  1. 1They sign in at your provider and land in the console. The account is created here automatically at that moment; you do not invite federated users first.
  2. 2Everything they try is refused. This is the expected state, not a fault. They hold no permission tier yet.
  3. 3An administrator opens Admin, Users. The new user is listed with no tier. Select Groups, pick their tiers, and save.
  4. 4They sign out and sign in again. Now they have the access you granted.

In the user’s group panel you will also see a group named after your provider, listed under the heading for groups the directory manages itself. Every federated user is joined to it automatically. It is not a permission tier and it is not a partition, it grants nothing, and the console never writes to it. Ignore it.

Users created directly here rather than through your provider behave differently on this one point: confirming a directory sign-up assigns a starting tier automatically. A federated user never passes through that step, which is exactly why the assignment is yours to make.

What federation is not

Federation here means human sign-in: SAML and OIDC, for people reaching the console and the API. It is unrelated to certificate enrollment, and the two get confused often enough to be worth stating plainly.

SanctiKey ships no certificate enrollment ecosystem. There is no ACME, no SCEP and no EST, no auto-enrollment, and no renewal agent. If your requirement is that a device or a load balancer enrolls itself over one of those protocols, that requirement is not met here, and we would rather you knew now than after signing.

What is provided is a certificate authority you drive: a root and intermediate hierarchy, CSR signing, issuance, revocation, and public CRL and OCSP distribution. Integration is your pipeline calling the REST API, plus the console. Renewal automation is your pipeline’s job. Signing, revocation, and revocation truth are ours.

Machine to machine access does not use federation either. API keys are issued from the API Keys tab in the console; OAuth2 service accounts are provisioned through the administrative API. Both carry scopes directly and neither involves your identity provider.