|
| 1 | +--- |
| 2 | +title: Authentication |
| 3 | +--- |
| 4 | +Most destinations require some sort of authentication. Segment's destination interface provides details about how customers need to authenticate with your destination to send data or retrieve data for dynamic input fields. |
| 5 | + |
| 6 | +## Basic Authentication |
| 7 | + |
| 8 | +Basic authentication is useful if your destination requires a username and password to authenticate. These are values that only the customer and the destination know. |
| 9 | + |
| 10 | +> success "" |
| 11 | +> When scaffolding your integration, select Basic Auth from the auto-prompt or pass `--template basic-auth`. |
| 12 | +
|
| 13 | +```js |
| 14 | +const authentication = { |
| 15 | + // the 'basic' authentication scheme tells Segment to automatically |
| 16 | + // include the `username` and `password` fields so you don't have to. |
| 17 | + // Segment will automatically do base64 header encoding of the username:password |
| 18 | + scheme: 'basic', |
| 19 | + |
| 20 | + fields: { |
| 21 | + username: { |
| 22 | + label: 'Username', |
| 23 | + description: 'Your username', |
| 24 | + type: 'string', |
| 25 | + required: true |
| 26 | + }, |
| 27 | + password: { |
| 28 | + label: 'password', |
| 29 | + description: 'Your password.', |
| 30 | + type: 'string', |
| 31 | + required: true |
| 32 | + } |
| 33 | + }, |
| 34 | + |
| 35 | + // a function that can test the user's credentials |
| 36 | + testRequest: (request) => { |
| 37 | + return request('https://example.com/api/accounts/me.json') |
| 38 | + } |
| 39 | +} |
| 40 | + |
| 41 | +const destination = { |
| 42 | + // ...other properties |
| 43 | + authentication, |
| 44 | + |
| 45 | + extendRequest({ settings }) { |
| 46 | + return { |
| 47 | + username: settings.username, |
| 48 | + password: settings.password |
| 49 | + } |
| 50 | + } |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +## Custom Authentication |
| 55 | + |
| 56 | +Custom authentication is the most commonly used authentication among Segment destinations. It's what most “API Key” based authentication should use. You’ll likely need to define an `extendRequest` function to complete the authentication by modifying request headers with some authentication input fields. |
| 57 | + |
| 58 | +```js |
| 59 | +const authentication = { |
| 60 | + // the 'custom' scheme doesn't do anything automagically for you, but let's you |
| 61 | + // define the behavior through input fields and `extendRequest`. |
| 62 | + // this is what most API key-based destinations should use |
| 63 | + scheme: 'custom', |
| 64 | + |
| 65 | + // a function that can test the user's credentials |
| 66 | + testRequest: (request) => { |
| 67 | + return request(`/accounts/me.json`) |
| 68 | + }, |
| 69 | + |
| 70 | + // fields that are specific to authentication |
| 71 | + fields: { |
| 72 | + subdomain: { |
| 73 | + type: 'string', |
| 74 | + label: 'Subdomain', |
| 75 | + description: 'The subdomain for your account, found in your user settings.', |
| 76 | + required: true |
| 77 | + }, |
| 78 | + apiKey: { |
| 79 | + type: 'string', |
| 80 | + label: 'API Key', |
| 81 | + description: 'Found on your settings page.', |
| 82 | + required: true |
| 83 | + } |
| 84 | + } |
| 85 | +} |
| 86 | + |
| 87 | +const destination = { |
| 88 | + // ...other properties |
| 89 | + authentication, |
| 90 | + // we may explore a simple JSON representation that supports template strings |
| 91 | + extendRequest: ({ settings }) => { |
| 92 | + return { |
| 93 | + prefixUrl: `https://${settings.subdomain}.example.com/api`, |
| 94 | + headers: { Authorization: `Bearer ${settings.apiKey}` }, |
| 95 | + responseType: 'json' |
| 96 | + } |
| 97 | + } |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +## OAuth 2.0 Managed |
| 102 | + |
| 103 | +If your API supports [OAuth 2.0](https://oauth.net/2/){:target="_blank"}, you can authenticate your destination's users with it. |
| 104 | + |
| 105 | +```js |
| 106 | +const authentication = { |
| 107 | + // the 'oauth-managed' authentication scheme tells Segment use the |
| 108 | + // oauth credentials and endpoint that you provide to authenticate users. |
| 109 | + scheme: 'oauth-managed', |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +When you receive access to the Developer Portal, find your integration, and navigate to the **OAuth settings** tab to configure the integration's OAuth details. |
0 commit comments