WorkOS PHP SDK

SSO
in package

Application

Properties

$client : HttpClient

Methods

__construct() : mixed
authorizeLogout() : SSOLogoutAuthorizeResponse: Logout Authorize
createConnection() : Connection: Create a Connection
createConnectionSAMLIdpSigningCert() : SAMLIdpSigningCertificate: Create an IdP signing certificate
createConnectionSAMLSpEncryptionCert() : SAMLSpEncryptionCertificate: Create an SP encryption certificate
createConnectionSAMLSpSigningCert() : SAMLSpSigningCertificate: Create an SP signing certificate
deleteConnection() : void: Delete a Connection
deleteConnectionSAMLIdpSigningCert() : void: Delete an IdP signing certificate
deleteConnectionSAMLSpEncryptionCert() : void: Delete an SP encryption certificate
deleteConnectionSAMLSpSigningCert() : void: Delete the SP signing certificate
getAuthorizationUrl() : string: Initiate SSO
getConnection() : Connection: Get a Connection
getLogoutUrl() : string: Logout Redirect
getProfile() : Profile: Get a User Profile
getProfileAndToken() : SSOTokenResponse: Get a Profile and Token
listConnections() : PaginatedResponse<string|int, Connection>: List Connections
listConnectionSAMLIdpSigningCerts() : SAMLIdpSigningCertificateList: List IdP signing certificates
listConnectionSAMLSpEncryptionCerts() : SAMLSpEncryptionCertificateList: List SP encryption certificates
listConnectionSAMLSpSigningCert() : SAMLSpSigningCertificate: Get the SP signing certificate
updateConnection() : Connection: Update a Connection

$client read-only


        private
            HttpClient
    $client

__construct()


    public
                    __construct(HttpClient $client) : mixed

Parameters

$client : HttpClient

authorizeLogout()

Logout Authorize


    public
                    authorizeLogout(string $profileId[, RequestOptions|null $options = null ]) : SSOLogoutAuthorizeResponse

You should call this endpoint from your server to generate a logout token which is required for the Logout Redirect endpoint.

Parameters

$profileId : string: The unique ID of the profile to log out.
$options : RequestOptions|null = null

Return values

SSOLogoutAuthorizeResponse

createConnection()

Create a Connection


    public
                    createConnection(string $organizationId, CreateProtocolOptionsSAML|CreateProtocolOptionsOIDC $protocolOptions[, string|null $name = null ][, string|null $externalId = null ][, string|null $connectionType = null ][, CreateConnectionAttributeMaps|null $attributeMaps = null ][, RequestOptions|null $options = null ]) : Connection

Creates a new connection for an organization. Provide saml_options or oidc_options to configure the identity provider. When external_id matches an existing connection in the organization, that connection is returned instead of creating a duplicate.

Parameters

$organizationId : string: Unique identifier for the Organization in which the Connection resides.
$protocolOptions : CreateProtocolOptionsSAML|CreateProtocolOptionsOIDC
$name : string|null = null: A human-readable name for the Connection. This will most commonly be the organization's name.
$externalId : string|null = null: The customer-owned identifier for the Connection.
$connectionType : string|null = null: The type of the Connection. Only SAML and OIDC connection types may be created. When omitted, the type is inferred from the provided options.
$attributeMaps : CreateConnectionAttributeMaps|null = null: How IdP attributes or claims map onto WorkOS profile fields. Provided fields override the defaults for the connection type.
$options : RequestOptions|null = null

Return values

Connection

createConnectionSAMLIdpSigningCert()

Create an IdP signing certificate


    public
                    createConnectionSAMLIdpSigningCert(string $connectionId, string $value[, RequestOptions|null $options = null ]) : SAMLIdpSigningCertificate

Adds an Identity Provider signing certificate to the connection, so SAML responses signed with its key can be verified. Use this to import a new certificate ahead of an Identity Provider rotation — the existing certificates keep working until they are deleted or expire.

Parameters

$connectionId : string: Unique identifier for the Connection.
$value : string: The PEM-encoded X.509 certificate.
$options : RequestOptions|null = null

Return values

SAMLIdpSigningCertificate

createConnectionSAMLSpEncryptionCert()

Create an SP encryption certificate


    public
                    createConnectionSAMLSpEncryptionCert(string $connectionId[, RequestOptions|null $options = null ]) : SAMLSpEncryptionCertificate

Generates a new encryption key pair for the connection and returns its public certificate. WorkOS holds the private key, so the request takes no body — to bring your own key pairs, provide saml_options.sp_encryption_key_pairs when creating the connection instead. Creating a certificate appends rather than replaces: every active private key is tried when decrypting, which lets a rotation overlap the old and new certificates.

Parameters

$connectionId : string: Unique identifier for the Connection.
$options : RequestOptions|null = null

Return values

SAMLSpEncryptionCertificate

createConnectionSAMLSpSigningCert()

Create an SP signing certificate


    public
                    createConnectionSAMLSpSigningCert(string $connectionId[, RequestOptions|null $options = null ]) : SAMLSpSigningCertificate

Generates a new request signing key pair for the connection and returns its public certificate. WorkOS holds the private key, so the request takes no body — to bring your own key pair, provide saml_options.sp_signing_key_pair when creating the connection instead. A connection signs with one key pair at a time: delete the existing certificate before creating its replacement.

Parameters

$connectionId : string: Unique identifier for the Connection.
$options : RequestOptions|null = null

Return values

SAMLSpSigningCertificate

deleteConnection()

Delete a Connection


    public
                    deleteConnection(string $id[, RequestOptions|null $options = null ]) : void

Permanently deletes an existing connection. It cannot be undone.

Parameters

$id : string: Unique identifier for the Connection.
$options : RequestOptions|null = null

deleteConnectionSAMLIdpSigningCert()

Delete an IdP signing certificate


    public
                    deleteConnectionSAMLIdpSigningCert(string $connectionId, string $certificateId[, RequestOptions|null $options = null ]) : void

Removes an Identity Provider signing certificate from the connection. The last remaining certificate cannot be deleted. A certificate still published in the Identity Provider metadata may be restored by a metadata refresh.

Parameters

$connectionId : string: Unique identifier for the Connection.
$certificateId : string: Unique identifier for the Identity Provider signing certificate.
$options : RequestOptions|null = null

deleteConnectionSAMLSpEncryptionCert()

Delete an SP encryption certificate


    public
                    deleteConnectionSAMLSpEncryptionCert(string $connectionId, string $certificateId[, RequestOptions|null $options = null ]) : void

Removes an encryption key pair from the connection. SAML responses encrypted with its certificate can no longer be decrypted, so remove the certificate from the Identity Provider first when rotating.

Parameters

$connectionId : string: Unique identifier for the Connection.
$certificateId : string: Unique identifier for the Service Provider encryption key pair. WorkOS holds the corresponding private key, which is never exposed.
$options : RequestOptions|null = null

deleteConnectionSAMLSpSigningCert()

Delete the SP signing certificate


    public
                    deleteConnectionSAMLSpSigningCert(string $connectionId, string $certificateId[, RequestOptions|null $options = null ]) : void

Removes the request signing key pair from the connection, after which SAML requests are sent unsigned. Delete the certificate before creating its replacement when rotating.

Parameters

$connectionId : string: Unique identifier for the Connection.
$certificateId : string: Unique identifier for the Service Provider signing key pair. WorkOS holds the corresponding private key, which is never exposed.
$options : RequestOptions|null = null

getAuthorizationUrl()

Initiate SSO


    public
                    getAuthorizationUrl(string $redirectUri[, array<string|int, string>|null $providerScopes = null ][, array<string, string>|null $providerQueryParams = null ][, string|null $domain = null ][, SSOProvider|null $provider = null ][, string|null $state = null ][, string|null $connection = null ][, string|null $organization = null ][, string|null $domainHint = null ][, string|null $loginHint = null ][, string|null $nonce = null ][, string|null $prompt = null ][, RequestOptions|null $options = null ]) : string

Initiates the single sign-on flow.

Parameters

$redirectUri : string: Where to redirect the user after they complete the authentication process. You must use one of the redirect URIs configured via the Redirects page on the dashboard.
$providerScopes : array<string|int, string>|null = null: Additional scopes to request from the identity provider. Applicable when using OAuth or OpenID Connect connections.
$providerQueryParams : array<string, string>|null = null: Key/value pairs of query parameters to pass to the OAuth provider. Only applicable when using OAuth connections.
$domain : string|null = null: (deprecated) Deprecated. Use connection or organization instead. Used to initiate SSO for a connection by domain. The domain must be associated with a connection in your WorkOS environment.
$provider : SSOProvider|null = null: Used to initiate OAuth authentication with various providers.
$state : string|null = null: An optional parameter that can be used to encode arbitrary information to help restore application state between redirects. If included, the redirect URI received from WorkOS will contain the exact state that was passed.
$connection : string|null = null: Used to initiate SSO for a connection. The value should be a WorkOS connection ID.

You can persist the WorkOS connection ID with application user or team identifiers. WorkOS will use the connection indicated by the connection parameter to direct the user to the corresponding IdP for authentication.
$organization : string|null = null: Used to initiate SSO for an organization. The value should be a WorkOS organization ID.

You can persist the WorkOS organization ID with application user or team identifiers. WorkOS will use the organization ID to determine the appropriate connection and the IdP to direct the user to for authentication.
$domainHint : string|null = null: Can be used to pre-fill the domain field when initiating authentication with Microsoft OAuth or with a Google SAML connection type.
$loginHint : string|null = null: Can be used to pre-fill the username/email address field of the IdP sign-in page for the user, if you know their username ahead of time. Currently supported for OAuth, OpenID Connect, Okta, Entra ID, and custom SAML connections.
$nonce : string|null = null: A random string generated by the client that is used to mitigate replay attacks.
$prompt : string|null = null: If set to login, forces re-authentication at the identity provider. For supported SAML providers this sets ForceAuthn="true" in the SAML request; providers that don't support it are unaffected.
$options : RequestOptions|null = null

Return values

string

getConnection()

Get a Connection


    public
                    getConnection(string $id[, RequestOptions|null $options = null ]) : Connection

Get the details of an existing connection.

Parameters

$id : string: Unique identifier for the Connection.
$options : RequestOptions|null = null

Return values

Connection

getLogoutUrl()

Logout Redirect


    public
                    getLogoutUrl(string $token[, RequestOptions|null $options = null ]) : string

Logout allows to sign out a user from your application by triggering the identity provider sign out flow. This GET endpoint should be a redirection, since the identity provider user will be identified in the browser session.

Before redirecting to this endpoint, you need to generate a short-lived logout token using the Logout Authorize endpoint.

Parameters

$token : string: The logout token returned from the Logout Authorize endpoint.
$options : RequestOptions|null = null

Return values

string

getProfile()

Get a User Profile


    public
                    getProfile([RequestOptions|null $options = null ]) : Profile

Exchange an access token for a user's Profile. Because this profile is returned in the Get a Profile and Token endpoint your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user's profile.

Parameters

$options : RequestOptions|null = null

Return values

Profile

getProfileAndToken()

Get a Profile and Token


    public
                    getProfileAndToken([string|null $code = null ][, string|null $subjectToken = null ][, string|null $subjectTokenType = null ][, string|null $organizationId = null ][, RequestOptions|null $options = null ]) : SSOTokenResponse

Get an access token along with the user Profile using the code passed to your Redirect URI.

Parameters

$code : string|null = null: The authorization code received from the authorization callback. Required when grant_type is authorization_code.
$subjectToken : string|null = null: The OIDC ID token to exchange. Required when grant_type is urn:ietf:params:oauth:grant-type:token-exchange. Must be sent in the request body.
$subjectTokenType : string|null = null: The type of the subject token. Required when grant_type is urn:ietf:params:oauth:grant-type:token-exchange. Must be sent in the request body.
$organizationId : string|null = null: The ID of the organization whose connection the subject token is validated against. Required when grant_type is urn:ietf:params:oauth:grant-type:token-exchange. Must be sent in the request body.
$options : RequestOptions|null = null

Return values

SSOTokenResponse

listConnections()

List Connections


    public
                    listConnections([string|null $before = null ][, string|null $after = null ][, int|null $limit = null ][, PaginationOrder $order = PaginationOrder::Desc ][, ConnectionsConnectionType|null $connectionType = null ][, string|null $domain = null ][, string|null $organizationId = null ][, string|null $search = null ][, RequestOptions|null $options = null ]) : PaginatedResponse<string|int, Connection>

Get a list of all of your existing connections matching the criteria specified.

Parameters

$before : string|null = null: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
$after : string|null = null: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
$limit : int|null = null: Upper limit on the number of objects to return, between 1 and 100. Defaults to 10.
$order : PaginationOrder = PaginationOrder::Desc: Order the results by the creation time. Defaults to "desc".
$connectionType : ConnectionsConnectionType|null = null: Filter Connections by their type.
$domain : string|null = null: Filter Connections by their associated domain.
$organizationId : string|null = null: Filter Connections by their associated organization.
$search : string|null = null: Searchable text to match against Connection names.
$options : RequestOptions|null = null

Return values

PaginatedResponse<string|int, Connection>

listConnectionSAMLIdpSigningCerts()

List IdP signing certificates


    public
                    listConnectionSAMLIdpSigningCerts(string $connectionId[, RequestOptions|null $options = null ]) : SAMLIdpSigningCertificateList

Lists every Identity Provider signing certificate on the connection, including expired ones, oldest first.

Parameters

$connectionId : string: Unique identifier for the Connection.
$options : RequestOptions|null = null

Return values

SAMLIdpSigningCertificateList

listConnectionSAMLSpEncryptionCerts()

List SP encryption certificates


    public
                    listConnectionSAMLSpEncryptionCerts(string $connectionId[, RequestOptions|null $options = null ]) : SAMLSpEncryptionCertificateList

Lists the public certificates the Identity Provider can use to encrypt SAML responses sent to WorkOS, including expired ones, oldest first.

Parameters

$connectionId : string: Unique identifier for the Connection.
$options : RequestOptions|null = null

Return values

SAMLSpEncryptionCertificateList

listConnectionSAMLSpSigningCert()

Get the SP signing certificate


    public
                    listConnectionSAMLSpSigningCert(string $connectionId[, RequestOptions|null $options = null ]) : SAMLSpSigningCertificate

Returns the public certificate the Identity Provider can use to verify the signature of SAML requests sent by WorkOS. Responds with 404 when the connection has no request signing key pair.

Parameters

$connectionId : string: Unique identifier for the Connection.
$options : RequestOptions|null = null

Return values

SAMLSpSigningCertificate

updateConnection()

Update a Connection


    public
                    updateConnection(string $id[, string|null $name = null ][, string|null $externalId = null ][, string|null $connectionType = null ][, PatchConnectionAttributeMaps|null $attributeMaps = null ][, null|PatchProtocolOptionsSAML|PatchProtocolOptionsOIDC $protocolOptions = null ][, RequestOptions|null $options = null ]) : Connection

Updates an existing connection. Only the provided fields are changed; fields that accept null are reset to their default behavior.

Parameters

$id : string: Unique identifier for the Connection.
$name : string|null = null: A human-readable name for the Connection.
$externalId : string|null = null: The customer-owned identifier for the Connection. Set to null to stop tracking one.
$connectionType : string|null = null: The type of the Connection. Immutable after creation — it may be sent, but only with the Connection current type.
$attributeMaps : PatchConnectionAttributeMaps|null = null: How IdP attributes or claims map onto WorkOS profile fields. Only the provided fields are updated.
$protocolOptions : null|PatchProtocolOptionsSAML|PatchProtocolOptionsOIDC = null
$options : RequestOptions|null = null

Return values

Connection

SSO in package Application

Table of Contents

Properties

Methods

Properties

$client read-only

Methods

__construct()

Parameters

authorizeLogout()

Parameters

Tags

Return values

createConnection()

Parameters

Tags

Return values

createConnectionSAMLIdpSigningCert()

Parameters

Tags

Return values

createConnectionSAMLSpEncryptionCert()

Parameters

Tags

Return values

createConnectionSAMLSpSigningCert()

Parameters

Tags

Return values

deleteConnection()

Parameters

Tags

deleteConnectionSAMLIdpSigningCert()

Parameters

Tags

deleteConnectionSAMLSpEncryptionCert()

Parameters

Tags

deleteConnectionSAMLSpSigningCert()

Parameters

Tags

getAuthorizationUrl()

Parameters

Tags

Return values

getConnection()

Parameters

Tags

Return values

getLogoutUrl()

Parameters

Return values

getProfile()

Parameters

Tags

Return values

getProfileAndToken()

Parameters

Tags

Return values

listConnections()

Parameters

Tags

Return values

listConnectionSAMLIdpSigningCerts()

Parameters

Tags

Return values

listConnectionSAMLSpEncryptionCerts()

Parameters

Tags

Return values

listConnectionSAMLSpSigningCert()

Parameters

Tags

Return values

updateConnection()

Parameters

Tags

Return values

SSO
in package

Application