diff --git a/fern/docs.yml b/fern/docs.yml index 8884cfb..69378c9 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -124,3 +124,19 @@ redirects: destination: "/docs/saml/saml-quickstart" - source: "/docs/scim-quickstart" destination: "/docs/scim/scim-quickstart" + - source: "/docs/sso-ready-concepts/overview" + destination: "/docs/ssoready-concepts/overview" + - source: "/docs/sso-ready-concepts/environments" + destination: "/docs/ssoready-concepts/environments" + - source: "/docs/sso-ready-concepts/organizations" + destination: "/docs/ssoready-concepts/organizations" + - source: "/docs/sso-ready-concepts/saml-connections" + destination: "/docs/ssoready-concepts/saml-connections" + - source: "/docs/sso-ready-concepts/login-flows" + destination: "/docs/ssoready-concepts/login-flows" + - source: "/docs/sso-ready-concepts/scim-directories" + destination: "/docs/ssoready-concepts/scim-directories" + - source: "/docs/sso-ready-concepts/scim-users" + destination: "/docs/ssoready-concepts/scim-users" + - source: "/docs/sso-ready-concepts/scim-groups" + destination: "/docs/ssoready-concepts/scim-groups" diff --git a/fern/pages/saml-quickstart.mdx b/fern/pages/saml-quickstart.mdx index c14f54c..76b3b13 100644 --- a/fern/pages/saml-quickstart.mdx +++ b/fern/pages/saml-quickstart.mdx @@ -55,16 +55,42 @@ to redirect your user to a URL. SSOReady's SDKs generate a URL for you, and then you simply forward your user to that URL using any mechanism that suits your tech stack. -```bash cURL + + +```bash title="cURL" curl https://api.ssoready.com/v1/saml/redirect \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ssoready_sk_..." \ -d '{ "organizationExternalId": "..." }' ``` +```typescript title="TypeScript" +const ssoready = new SSOReadyClient(); +await ssoready.saml.getSamlRedirectUrl({ + organizationExternalId: "...", +}); +``` + +```python title="Python" +client = SSOReady() +client.saml.get_saml_redirect_url( + organization_external_id="...", +) +``` + + + That code sample requires an API Key (`ssoready_sk_...`) and an `organizationExternalId`. How you get those is covered in [Setting up SSOReady](#setting-up-ssoready) later on this page. + + +For recommendations on how to incorporate a "Log in with SAML" button into your +login user experience, check out our docs on [Integrating SAML with your Login +UI](/docs/saml/integrating-saml-into-your-login-ui). + + + ## Handling SAML logins ![](quickstart-handle.png) @@ -79,6 +105,8 @@ So what you'll need to do is create a new "SSOReady callback page" (typically so `https://app.yourcompany.com/ssoready-callback`), where you'll expect a `?saml_access_code=saml_access_code_...` query parameter in the URL. From your backend, you'll exchange that access code for a user's details: + + ```bash cURL curl https://api.ssoready.com/v1/saml/redeem \ -H "Content-Type: application/json" \ @@ -86,6 +114,22 @@ curl https://api.ssoready.com/v1/saml/redeem \ -d '{ "samlAccessCode": "saml_access_code_..." }' ``` +```typescript title="TypeScript" +const ssoready = new SSOReadyClient(); +await ssoready.saml.redeemSamlAccessCode({ + samlAccessCode: "saml_access_code_...", +}); +``` + +```python title="Python" +client = SSOReady() +client.saml.redeem_saml_access_code( + saml_access_code="saml_access_code_...", +) +``` + + + The response will include the user's `email` as well as the SSOReady `organizationId` and `organizationExternalId` they belong to. It's your responsibility to then log the user in with that given email and organization using whatever mechanism your tech stack uses. @@ -93,6 +137,14 @@ mechanism your tech stack uses. How you tell us about your desired "SSOReady callback page", as well as what `organizationId` and `organizationExternalId` mean, is covered in [Setting up SSOReady](#setting-up-ssoready) below. + + +For recommendations on how your SAML handling logic should work, check out our +docs on [Handling SAML Logins and Just-in-Time +Provisioning](/docs/saml/handling-saml-logins-jit-provisioning). + + + # Setting up SSOReady In [Code implementation](#code-implementation), there were three missing pieces that you'd need to implement SSOReady: diff --git a/fern/pages/ssoready-concepts/environments.mdx b/fern/pages/ssoready-concepts/environments.mdx index 7c15f13..ff3ad77 100644 --- a/fern/pages/ssoready-concepts/environments.mdx +++ b/fern/pages/ssoready-concepts/environments.mdx @@ -1,7 +1,7 @@ --- title: 'SSOReady concepts: Environments' description: 'Understanding Environments in SSOReady' -noindex: false +slug: ssoready-concepts/environments --- ### Structuring SSOReady Environments diff --git a/fern/pages/ssoready-concepts/login-flows.mdx b/fern/pages/ssoready-concepts/login-flows.mdx index af16efa..bc74457 100644 --- a/fern/pages/ssoready-concepts/login-flows.mdx +++ b/fern/pages/ssoready-concepts/login-flows.mdx @@ -1,7 +1,7 @@ --- title: 'SSOReady concepts: Login Flows' description: 'Understanding Login Flows in SSOReady' -noindex: false +slug: ssoready-concepts/login-flows --- Each time one of your users attempts to log in via SAML, SSOReady will create a *Login Flow*. Login Flows store data related to your user's login attempt. Reviewing this data can help you audit and debug your [SAML Connections](saml-connections). diff --git a/fern/pages/ssoready-concepts/organizations.mdx b/fern/pages/ssoready-concepts/organizations.mdx index 3482df1..9f4dd39 100644 --- a/fern/pages/ssoready-concepts/organizations.mdx +++ b/fern/pages/ssoready-concepts/organizations.mdx @@ -1,7 +1,7 @@ --- title: 'SSOReady concepts: Organizations' description: 'Understanding Organizations in SSOReady' -noindex: false +slug: ssoready-concepts/organizations --- In SSOReady, each [Environment](environments) has some number of *Organizations*. @@ -56,4 +56,4 @@ Each Organization you set up in SSOReady can have one or more SAML Connections. ### Bulk updates -SSOReady does not currently support bulk updates (e.g. CSV uploads) to Organizations. Similarly, SSOReady does not currently surface an public endpoint for creating Organizations. You will need to create Organizations from the web application. If you have a large volume of data to process, please get in touch at contact@ssoready.com, and we can help. \ No newline at end of file +SSOReady does not currently support bulk updates (e.g. CSV uploads) to Organizations. Similarly, SSOReady does not currently surface an public endpoint for creating Organizations. You will need to create Organizations from the web application. If you have a large volume of data to process, please get in touch at contact@ssoready.com, and we can help. diff --git a/fern/pages/ssoready-concepts/overview.mdx b/fern/pages/ssoready-concepts/overview.mdx index 3b80220..27338a9 100644 --- a/fern/pages/ssoready-concepts/overview.mdx +++ b/fern/pages/ssoready-concepts/overview.mdx @@ -1,7 +1,7 @@ --- title: 'SSOReady concepts: overview' description: 'Understanding and navigating our product' -noindex: false +slug: ssoready-concepts/overview --- SSOReady introduces a small number of important concepts that you'll need to understand. This section of the documentation describes each of them and outlines explicit instructions where relevant. @@ -15,5 +15,3 @@ You may find it helpful to imagine SSOReady's concepts in a hierarchical structu
  • Organizations can have [SAML Connections](saml-connections) that belong to them
  • SAML Connections can have [Configurations](configurations) and [Login Flows](login-flows) that belong to them
    • - - diff --git a/fern/pages/ssoready-concepts/saml-connections.mdx b/fern/pages/ssoready-concepts/saml-connections.mdx index 600b140..721ff59 100644 --- a/fern/pages/ssoready-concepts/saml-connections.mdx +++ b/fern/pages/ssoready-concepts/saml-connections.mdx @@ -1,7 +1,7 @@ --- title: 'SSOReady concepts: SAML Connections' description: 'Understanding SAML Connections in SSOReady' -noindex: false +slug: ssoready-concepts/saml-connections --- SAML Connections store the information that SSOReady needs in order to connect your application with your customer's identity provider. diff --git a/fern/pages/ssoready-concepts/scim-directories.mdx b/fern/pages/ssoready-concepts/scim-directories.mdx index 835d5e7..089c0f4 100644 --- a/fern/pages/ssoready-concepts/scim-directories.mdx +++ b/fern/pages/ssoready-concepts/scim-directories.mdx @@ -1,7 +1,7 @@ --- title: 'SSOReady concepts: SCIM Directories' description: 'Understanding SCIM Directories in SSOReady' -noindex: false +slug: ssoready-concepts/scim-directories --- SCIM directory sync allows you to communicate with your customer's identity provider (or *directory*) regarding users and their privileges in your application. Most commonly, your customers will wish to provision and deprovision users in their identity provider and subsequently have those users provisioned or deprovisioned in your application. diff --git a/fern/pages/ssoready-concepts/scim-groups.mdx b/fern/pages/ssoready-concepts/scim-groups.mdx index 8793183..5839049 100644 --- a/fern/pages/ssoready-concepts/scim-groups.mdx +++ b/fern/pages/ssoready-concepts/scim-groups.mdx @@ -1,7 +1,7 @@ --- title: 'SSOReady concepts: SCIM Groups' description: 'Understanding SCIM Groups in SSOReady' -noindex: false +slug: ssoready-concepts/scim-groups --- SCIM defines *Groups* as a standard concept in its [specification](https://datatracker.ietf.org/doc/html/rfc7643). SSOReady uses *SCIM Groups* to homogenize varying implementations of *Groups* on your behalf. @@ -60,6 +60,3 @@ Please be aware that `attributes` will frequently vary. SCIM allows a lot of cus # SCIM Users Here you can find a list of the SCIM Users associated with the SCIM Group. You may click on their IDs to view more detail. - - - diff --git a/fern/pages/ssoready-concepts/scim-users.mdx b/fern/pages/ssoready-concepts/scim-users.mdx index cf88079..46c3e8e 100644 --- a/fern/pages/ssoready-concepts/scim-users.mdx +++ b/fern/pages/ssoready-concepts/scim-users.mdx @@ -1,7 +1,7 @@ --- title: 'SSOReady concepts: SCIM Users' description: 'Understanding SCIM Users in SSOReady' -noindex: false +slug: ssoready-concepts/scim-users --- SCIM defines *Users* as a standard concept in its [specification](https://datatracker.ietf.org/doc/html/rfc7643). SSOReady uses *SCIM Users* to homogenize varying implementations of *Users* on your behalf. @@ -78,4 +78,4 @@ Please be aware that `attributes` will frequently vary. SCIM allows a lot of cus # SCIM Groups -Here you can find a list of the SCIM Groups associated with the SCIM User. You may click on their IDs to view more detail. \ No newline at end of file +Here you can find a list of the SCIM Groups associated with the SCIM User. You may click on their IDs to view more detail.