Concepts
SSO glossary
Enterprise identity has an unusual amount of vocabulary for the amount of work it does, and much of it comes from specifications written twenty years apart. This page defines the terms you will actually meet in a setup call, grouped by where you meet them.
The parties
| Term | Definition |
|---|---|
| Identity provider (IdP) | The system that holds the accounts and performs authentication. Your customer runs it; you never do. |
| Service provider (SP) | The application accepting the authentication. In every one of these documents, that is you. |
| Relying party (RP) | The OIDC name for a service provider. Same role, different specification. |
| Principal | The person signing in. Also called the subject. |
| Tenant | One customer's isolated space in your product. Usually modelled as an organization. |
SAML vocabulary
| Term | Definition |
|---|---|
| Assertion | The signed XML statement saying who authenticated, when, and with what attributes. |
| ACS URL | Assertion consumer service — the endpoint where the identity provider POSTs the assertion. Also called the reply URL. |
| Entity ID | A stable identifier for your application, used as the assertion's intended audience. Also called the audience URI. |
| Name ID | The subject identifier inside an assertion. Its format decides whether it is stable across sign-ins. |
| Metadata | An XML document describing endpoints and certificates. Exchanging it is how two systems agree on a connection. |
| SP-initiated | A sign-in that starts at your application and is redirected to the identity provider. |
| IdP-initiated | A sign-in that starts from a tile in the customer's application launcher and arrives at your ACS URL unannounced. |
| Attribute statement | The block of extra claims — name, groups, employee ID — carried alongside the name ID. |
OIDC and OAuth vocabulary
| Term | Definition |
|---|---|
| ID token | A signed JWT proving an authentication happened. Meant for your application, and only for it. |
| Access token | A credential for calling an API. Opaque to you unless you own that API. |
| Refresh token | A long-lived credential exchanged for new access tokens. Treat it like a password. |
| Authorization code | A single-use, short-lived value exchanged server-side for tokens. |
| PKCE | Proof Key for Code Exchange — binds the code to the client that requested it, so an intercepted code is useless. |
| Scope | The set of permissions a token is requested with. Ask for the minimum a customer's IT team will accept. |
| Claim | One field inside a token: sub, email, name, and so on. |
| Discovery document | The well-known JSON file listing a provider's endpoints and key URL, so nothing has to be hardcoded. |
| JWKS | The published set of public keys used to verify token signatures, refetched when a key rotates. |
Provisioning vocabulary
| Term | Definition |
|---|---|
| SCIM | The REST protocol an identity provider uses to create, update and deactivate accounts in your product. |
| Provisioning | Creating an account before or without a sign-in. |
| Deprovisioning | Removing access when somebody leaves. The part a security review asks about. |
| JIT provisioning | Just-in-time — creating the account at first sign-in from the SSO profile, with no directory involved. |
| HRIS | The HR system of record. Sometimes the true source of who works at a company, ahead of the directory. |
| Directory group | A group defined in the customer's directory. Its name is theirs; its meaning in your product is yours. |
| Attribute mapping | Deciding which incoming claim populates which field on your user record. |
Operational vocabulary
| Term | Definition |
|---|---|
| Connection | One configured link between your application and one customer's identity provider. |
| Domain verification | Proving a customer controls an email domain, so a sign-in from it can be routed to their connection. |
| Home realm discovery | Deciding which connection an email address belongs to before authentication starts. |
| Step-up authentication | Asking for another factor before a sensitive action, even though the session is already valid. |
| Session fixation | An attack where an attacker plants a session identifier before sign-in. Rotating the session on authentication prevents it. |
| Break-glass account | A local account kept outside SSO so an outage at the identity provider does not lock everyone out. |
| Clock skew | Time drift between two servers. Assertions and tokens have narrow validity windows, so drift looks like a signature failure. |
Break-glass accounts come up in almost every enterprise security review. Having an answer — and a way to audit the use of such an account — is worth more than having a clever one.
The words in one record
Most of this vocabulary appears together the first time you read a connection back from the API. Here is where each term lands.
connection.json
1{2 "id": "conn_01HQZX8N4T",3 "organizationId": "org_01HQZX8N4T",4 "connectionType": "SAML",5 "state": "active",6 "domains": [{ "domain": "foo-corp.example", "state": "verified" }],7 "saml": {8 "entityId": "https://api.paycux.com/sso/saml/conn_01HQZX8N4T",9 "acsUrl": "https://api.paycux.com/sso/saml/acs/conn_01HQZX8N4T",10 "idpSignOnUrl": "https://idp.foo-corp.example/app/sso/saml",11 "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",12 "certificateExpiresAt": "2028-03-01T00:00:00Z"13 },14 "attributeMapping": {15 "email": "urn:oid:0.9.2342.19200300.100.1.3",16 "firstName": "urn:oid:2.5.4.42",17 "lastName": "urn:oid:2.5.4.4"18 }19}