The platform server supports multiple providers for user identification or grabbing tokens for authentication to third-party services. Out of the box, you can sign in with any Google or Apple identity by trusting the central auth server, but any workspace can be configured to work with other providers using OAuth, or OpenID Connect. See below for bootstrapping a new instance without G-Suite set up.

The general syntax is documented here, but there is also a wiki page of working examples and provider-specific tips and tricks: https://github.com/remixlabs/amp/wiki/Auth-plugin-examples.

For 3rd-party token flows, where you want the client to have an access token to some external service, we follow the OAuth2 spec in distinguishing "public" and "confidential" clients; the configuration details for a public client can be publicly distributed freely, for example, to a desktop or mobile app that a user can inspect. Confidential configurations can be used via a server flow but not retrieved or edited except for admins; public configurations can be read by anyone, created by any signed-in user, and modified by their creator or an admin. In particular, a public configuration can be registered on a central amp server and then fetched on demand in a local client to run an on-device auth flow.

Server API

Public configurations

GET    /x/authConfig/public          # list all public configs
GET    /x/authConfig/public/{name}   # get public config by name
POST   /x/authConfig/public          # create new public config
PUT    /x/authConfig/public/{name}   # update (replace) config
PATCH  /x/authConfig/public/{name}   # upsert (merge into existing) config
DELETE /x/authConfig/public/{name}   # delete public config

The two GET endpoints are publicly callable (no authentication required). Creating a public configuration is authenticated but any signed-in user is allowed to create new configuration. Update/upsert/delete is restricted to the original creator (owner) of the configuration, or an admin.

Confidential configurations

GET    /x/authConfig          # list all configs
GET    /x/authConfig/{name}   # get config by name
POST   /x/authConfig          # create new config
PUT    /x/authConfig/{name}   # update (replace) config
PATCH  /x/authConfig/{name}   # upsert (merge into existing) config
DELETE /x/authConfig/{name}   # delete config

The confidential endpoints are identical in form but with different access rules. All of these require admin access. Editing a public configuration via the normal endpoints will convert it to a confidential configuration.

Configuration schema

Some example configurations:

[
  {
    "type": "oauth",
    "name": "ad_oauth",
    "client_id": "some_other_id",
    "client_secret": "ABC123",
    "auth_url": "<https://saml.autodesk.com/as/authorization.oauth2>",
    "auth_url_params": {
      "prompt": "consent"
    },
    "token_url": "<https://saml.autodesk.com/as/token.oauth2>",
    "userinfo_url": "<https://saml.autodesk.com/idp/userinfo.openid>",
    "scopes": [
      "openid",
      "email"
    ],
    "token_extras": [
      "instance_url"
    ],
    "headers": {
      "user-agent": [
        "com.remixlabs.runtime/1.0"
      ]
    }
  },
  {
    "type": "oidc",
    "name": "ad_oidc",
    "client_id": "some_other_id",
    "client_secret": "ABC123",
    "endpoint": "<https://login.microsoftonline.com/abc123/v2.0>",
    "offline": true,
    "scopes": [
      "openid",
      "email",
      "offline_access"
    ]
  },
  {
    "type": "apple",
    "name": "fooapp",
    "client_id": "com.remixlabs.fooapp",
    "client_secret": "generate_this_from_private_key"
  },
  {
    "type": "sfdc_oauth",
    "name": "sfdc_oauth",
    "default": true,
    "client_id": "my_id",
    "client_secret": "ABC123",
    "domain": "salesforce.com",
    "store_token": true,
    "token_lifetime": 3600
  }
]

Currently supported types are oauth, oidc, apple, and sfdc_oauth . Special handling is needed for Salesforce's OAuth flow because Salesforce does not support Open ID Connect; in particular, you need to get an access token to find out the appropriate endpoint to request identity information from. Because there is special handling for Salesforce flows, fewer fields are required.

The oauth, oidc, and sfdc_oauth plugins all implement PKCE. Since from the resource server side this just consists of applying extra parameters to the authorization and code exchange requests, we add the PKCE parameters for all flows whether or not the identity provider is known to support it.

When creating an OAuth/Open ID Connect integration in the identity provider ( IDP), you will have to specify the callback/redirect URL that the IDP should send you back to after you've signed in. For a plugin named myplugin, that will be $AMP_BASE/x/auth/myplugin/callback, e.g., https://remix-dev.remixlabs.com/a/x/auth/myplugin/callback.

To work in the desktop app, you'll need a callback URL like http://localhost:3434/a/x/auth/myplugin/callback. For mobile devices or development with a local amp server, use http://localhost:8000/x/auth/myplugin/callback. Some providers will let you set up all of these different callbacks in one configuration; for others you may need separate integrations for web, desktop, and mobile. When creating an auth flow that will be used on desktop or mobile -- and hence the client ID and secret will be stored somewhere the end user can access -- you should be sure to set up the configuration appropriately. Different providers handle this differently, but generally there is a way to specify that an OAuth configuration is intended to be used with native or desktop apps. You can override the default callback URL by setting the "callback" field in the plugin config. Note that the main reason to do this is to provide an acceptable callback to the identity provider while hosting the actual amp service locally, eg, on mobile. If the callback flow does not ultimately end up at the original amp server, the anti-CSRF check will fail, and the code-for-token exchange will not work. Thus, there is probably no reason to set this other than to an endpoint that will redirect to the default callback.

For a Sign In With Apple, flow, you need to first create a private key in the Developer Center, and then use this to create a client secret. The utility make-apple-secret is provided for this. Build with make make-apple-secret and run as bin/make-apple-secret from the main directory, with a file named key.p8 in that directory.

You can set at most one of the entries as default by setting the "default" key to true. This makes this the standard auth flow the builder and runtime use. (This is handled by making /x/auth redirect to which handler is default.) If you don't set a default, the standard G-Suite auth flow remains default.