Add SAML IdP
Add a SAML identity provider (IdP) to an endpoint, from its metadata: a URL ngris reads now and again every day, or the metadata pasted. It is on at once: your sign-in page shows Continue with <name> while sign-in with single sign-on is on ("mode": "sso"). First enter ngris's values in the IdP, and check its metadata if you like. In the dashboard: Add provider, then SAML, under Single sign-on in Sign-in & access › Sign-in.
Needs the endpoint_saml feature on the plan of the account that owns the endpoint (Enterprise) and the endpoints:write permission. Strict JSON decoding: unknown body fields return 400.
Path parameters
uuid string (uuid) Req
The endpoint's
uuid from /endpoints.An integer id in the path is refused with 400 integer_id_unsupported (see public IDs). Use the uuid.
Request body
name string Req
The button's name: Continue with <name>. At most 100 characters, and each IdP of the endpoint has its own.
metadata_url string
The IdP's metadata URL. It must be https on a public address, answer within 15 seconds and not redirect. ngris reads it now and every day, for new certificates. Give it or
metadata_xml, not both.metadata_xml string
The IdP's metadata, pasted (at most 1 MiB), for an IdP reachable only inside your network. It doesn't update itself.
join_mode string Req
anyone: anyone the IdP signs in joins at once, without the limit of 20 new users an hour (with sign-ups off, nobody joins). follow: joining follows the endpoint's sign-up settings, as for any single sign-on. The endpoint's email domain lists apply to both.email_domains array<string>
The only email domains this IdP may send, such as
["acme.com"]: only domains it manages. An answer whose email has another domain is refused, at every sign-in, and a user already on the endpoint with one of these emails (added or invited by you, active, with no other sign-in link) is connected to the IdP at their first sign-in. Matched exactly, so list a subdomain on its own. At most 100. Left out: any, and nobody is connected by email.email_attribute, name_attribute, groups_attribute string
The attributes to read the user's email, name and groups from. Default
email, name and groups.group_roles array<object>
Roles from the IdP's groups:
[{"group": "shop-admins", "role_uuid": "019b4b9d-d300-736b-8601-153b3d9f70aa"}], up to 100 rules, each role_uuid one of this endpoint's roles. At every sign-in a user gets each rule's role whose group is in the answer, exactly, letter case included, and loses the roles these rules gave that no group gives any more. Roles you give by hand stay.own_second_step boolean
true when the IdP asks a second step of everyone who signs in with it: its sign-ins then skip the endpoint's second step. Only set it if it really does: ngris can't check. Default false.Response (201 Created)
The IdP, as Get SAML IdP answers it: what ngris read from the metadata (entity_id, sso_url, certificates, want_requests_signed) and, in sp, its start link and ngris's metadata for it.
Errors
400 Bad Request
Invalid JSON or unknown fields; a missing or unusable field, named in the answer (
name, join_mode, email_domains, an attribute name, a rule's group or role_uuid); both metadata sources, or neither; or metadata ngris can't use, with why: a URL that isn't https, isn't public, redirects or doesn't answer, metadata over 1 MiB or with a document type declaration, a document that isn't SAML metadata or doesn't describe exactly one IdP with a signing certificate, an IdP that takes sign-in requests by POST only, or certificates that are all past their end date.401 Unauthorized
Missing auth.
403 Forbidden
Caller lacks the
endpoints:write permission, or the plan doesn't include SAML single sign-on ("code": "entitlement_required", "entitlement_required": "endpoint_saml").404 Not Found
Endpoint doesn't exist or doesn't belong to the calling account, or a rule names a role the endpoint doesn't have (
a group rule names a role this endpoint doesn't have).409 Conflict
The same IdP (its entity ID) is on the endpoint already, another IdP has this name, the endpoint has 20 IdPs, the endpoint has no address yet, or it is paused.
413 Payload Too Large
The request is too large: paste at most 1 MiB of metadata, or give its URL.503 Service Unavailable
SAML single sign-on isn't available yet. Try again in a few minutes.Request
curl -X POST "https://api.ngris.com/v1/endpoints/019bb1e4-e785-77d2-9966-c3cff31d0a0e/saml/idps" \
-H "X-API-KEY: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme SSO",
"metadata_url": "https://idp.example.com/metadata",
"join_mode": "anyone",
"email_domains": ["acme.com"],
"group_roles": [{"group": "shop-admins", "role_uuid": "019b4b9d-d300-736b-8601-153b3d9f70aa"}]
}'
CLI
ngris api saml-idps create 019bb1e4-e785-77d2-9966-c3cff31d0a0e \
--name "Acme SSO" \
--metadata-url "https://idp.example.com/metadata" \
--join-mode anyone \
--email-domains acme.com \
--group-roles '[{"group": "shop-admins", "role_uuid": "019b4b9d-d300-736b-8601-153b3d9f70aa"}]'
Response — 201 Created
{
"uuid": "019c6a2e-4b10-7c3d-9e21-5a7f0b8c1d23",
"name": "Acme SSO",
"enabled": true,
"entity_id": "https://idp.example.com/saml",
"sso_url": "https://idp.example.com/saml/sso",
"metadata_source": "url",
"join_mode": "anyone",
"linked_users": 0,
"sp": {
"entity_id": "https://app.example.com/_tunnel_auth/saml",
"acs_url": "https://app.example.com/_tunnel_auth/saml/acs",
"metadata_url": "https://app.example.com/_tunnel_auth/saml/metadata?idp=019c6a2e-4b10-7c3d-9e21-5a7f0b8c1d23",
"start_url": "https://app.example.com/_tunnel_auth/saml/start?idp=019c6a2e-4b10-7c3d-9e21-5a7f0b8c1d23",
"name_id_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
},
…
}
Was this helpful?