SDKS

PHP Laravel SDK

The WorkOS PHP Laravel SDK provides your applications convenient access to the WorkOS SSO API.

Installation

To get started, install the WorkOS PHP Laravel SDK via Composer by running:

Terminal

file_copy
composer require workos/workos-php-laravel

View the source on GitHub.


Configuration

To use the SDK you must first provide your API key and Project ID from the Developer Dashboard. By default, the SDK looks for the following environment variables:

  • WORKOS_API_KEY
  • WORKOS_PROJECT_ID

A configuration file is available and can be generated by running the following:

Terminal

file_copy
php artisan vendor:publish --provider="WorkOS\Laravel\WorkOSServiceProvider"

SSO

The SSO Class provides convenient functions for interacting with the WorkOS SSO product.

SSO->getAuthorizationUrl($domain, $redirectUri, $state, $provider)

Generate an Authorization URL to intitiate the WorkOS OAuth 2.0 flow.

SSO->getAuthorizationUrl accepts the following arguments:

  • $domain null|string - Domain of the user that will be going through SSO
  • $redirectUri null|string - URI to direct the user to upon successful completion of SSO
  • $state null|array - Associative array containing state that will be returned from WorkOS as a JSON encoded string
  • $provider null|\WorkOS\Resource\ConnectionType - Service provider that handles the identity of the user

Returns:

  • string

Example:

app.php

file_copy
$url = (new \WorkOS\SSO())->getAuthorizationUrl(
  'my-co.com',
  {redirectURI},
  null,
  null
);

SSO->getProfile($code)

Fetch a \WorkOS\Resource\Profile for an authenticated user.

SSO->getProfile accepts the following arguments:

  • $code string - Code returned by WorkOS on completion of authorization flow

Returns:

  • \WorkOS\Resource\Profile

Example:

app.php

file_copy
$profile = (new WorkOSSSO())->getProfile($code)

SSO->createConnection($source)

Create a Connection.

SSO->createConnection accepts the following arguments:

  • $source string - Token returned by WorkOS as a result of the WorkOS.js embed workflow.

Returns:

  • \WorkOS\Resource\Connection

Example:

app.php

file_copy
$connection = $sso->createConnection($token);

AuditTrail

The AuditTrail Class provides convenient functions for accessing the WorkOS Audit Trail product.

AuditTrail->createEvent($event, $idempotencyKey)

Create an Audit Trail event.

AuditTrail->createEvent accepts the following arguments:

  • $event array - Array representing an Audit Trail event of the form:
    • $event["action_type"] string - Corresponding CRUD category of event. Can be one of C, R, U, or D.
    • $event["actor_name"] string - Display name of the entity performing the action.
    • $event["actor_id"] string - Unique identifier of the entity performing the action.
    • $event["group"] string - A single organization containing related members. This will normally be the customer of a vendor's application.
    • $event[l"ocation"] string - Identifier for where the event originated. This will be an IP address (IPv4 or IPv6), hostname, or device ID.
    • $event["occurred_at"] string - ISO-8601 datetime at which the event happened, with millisecond precision.
    • $event["metadata"] string - Arbitrary key-value data containing information associated with the event. Note: There is a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.
    • $event["target_id"] string - Unique identifier of the object or resource being acted upon.
    • $event["target_name"] string - Display name of the object or resource that is being acted upon.
  • $idempotencyKey string - Unique key guaranteeing idempotency of events for 24 hours.

Returns:

  • boolean

Example:

app.php

file_copy
$now = (new DateTime())->format(DateTime::ISO8601);

$event = [
    "group" => "organization_id",
    "action" => "user.login",
    "action_type" => "C",
    "actor_name" => "[email protected]",
    "actor_id" => "user_id",
    "target_name" => "[email protected]",
    "target_id" => "user_id",
    "location" =>  "1.1.1.1",
    "occurred_at" => $now,
];

(new WorkOSAuditTrail())->createEvent($event);

DirectorySync

The DirectorySync Class provides convenient functions for interacting with the WorkOS Directory Sync product.

DirectorySync->listDirectories($domain, $search, $limit, $before, $after)

List Directories.

DirectorySync->listDirectories accepts the following arguments:

  • $domain null|string - Domain of a Directory
  • $search null|string - Searchable text for a Directory
  • $limit int - Maximum number of records to return
  • $before null|string - Pagination cursor to receive records before a provided ID
  • $after null|string - Pagination cursor to receive records after a provided ID

Returns:

  • Array composed of the following:
    • Before cursor
    • After cursor
    • Array of \WorkOS\Resource\Directory

Example:

app.php

file_copy
list($before, $after, $directories) = (new WorkOSDirectorySync())->listDirectories();

DirectorySync->listGroups($directory, $user, $limit, $before, $after)

List Directory Groups.

DirectorySync->listGroups accepts the following arguments:

  • $directory null|string - Directory ID
  • $user null|string - Directory User ID
  • $limit int - Maximum number of records to return
  • $before null|string - Pagination cursor to receive records before a provided ID
  • $after null|string - Pagination cursor to receive records after a provided ID

Returns:

  • Array composed of the following:
    • Before cursor
    • After cursor
    • Array of \WorkOS\Resource\DirectoryGroup

Example:

app.php

file_copy
list($before, $after, $groups) = (new WorkOSDirectorySync())->listGroups();

DirectorySync->getGroup($directoryGroup)

Get a Directory Group.

DirectorySync->getGroup accepts the following arguments:

  • $directoryGroup string - Directory Group ID

Returns:

  • \WorkOS\Resource\DirectoryGroup

Example:

app.php

file_copy
$group = (new WorkOSDirectorySync())->getGroup("directory_grp_id");

DirectorySync->listUsers($directory, $group, $limit, $before, $after)

List Directory Users.

DirectorySync->listUsers accepts the following arguments:

  • $directory null|string - Directory ID
  • $group null|string - Directory Group ID
  • $limit int - Maximum number of records to return
  • $before null|string - Pagination cursor to receive records before a provided ID
  • $after null|string - Pagination cursor to receive records after a provided ID

Returns:

  • Array composed of the following:
    • Before cursor
    • After cursor
    • Array of \WorkOS\Resource\DirectoryUser

Example:

app.php

file_copy
list($before, $after, $users) = (new WorkOSDirectorySync())->listUsers();

DirectorySync->getUser($directoryUser)

Get a Directory User.

DirectorySync->getUser accepts the following arguments:

  • $directoryUser string - Directory User ID

Returns:

  • \WorkOS\Resource\DirectoryUser

Example:

app.php

file_copy
$user = (new WorkOSDirectorySync())->getUser("directory_user_id");

Resources

\WorkOS\Resource\Profile

An instance of \WorkOS\Resource\Profile will have attributes and values similar to the following:

JSON

file_copy
{
  "connectionType": "OktaSAML",
  "email": "[email protected]{foo-corp.com}",
  "firstName": "User",
  "id": "prof_id",
  "idpId": "randomalphanum",
  "lastName": "Name"
}

\WorkOS\Resource\Connection

An instance of \WorkOS\Resource\Connection will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "conn_id",
  "domains": [
    [
      "id": "conn_dom_id",
      "domain": "foo-corp.com"
    ]
  ],
  "status": "linked",
  "name": "Foo Corp Okta",
  "connectionType": "OktaSAML",
  "oauthUid": null,
  "oauthSecret": null,
  "oauthRedirectUri": "http://my-co.com/sso/provider/callback",
  "samlEntityId": null,
  "samlIdpUrl": null,
  "samlRelyingPartyTrustCert": null,
  "samlX509Certs": null
}

\WorkOS\Resource\Directory

An instance of \WorkOS\Resource\Directory will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "directory_id",
  "externalKey": "external-key",
  "state": "linked",
  "type": "gsuite directory",
  "name": "user",
  "bearerToken": null,
  "projectId": "project_id",
  "domain": "foo-corp.com",
}

\WorkOS\Resource\DirectoryGroup

An instance of \WorkOS\Resource\DirectoryGroup will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "directory_grp_id",
  "name": "Developers"
}

\WorkOS\Resource\DirectoryUser

An instance of \WorkOS\Resource\Directory will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "directory_id",
  "externalKey": "external-key",
  "state": "linked",
  "type": "gsuite directory",
  "name": "user",
  "bearerToken": null,
  "projectId": "project_id",
  "domain": "foo-corp.com",
}