Salesforce では、Apexなどで利用できる指定ログイン情報をはじめ、外部オブジェクト(Salesforce Connect)やFiles Connectなどなど、シングルサインオンや外部Webシステムへと接続するための認証プロバイダという機能を提供しています。認証に携わる部分を集約することで、管理の一元化と単純化につながりお便利です。
なんですが、OAuth での接続をする場合に少しだけくせがあるので、その設定について説明します。今回は例として、Salesforceクロス組織接続のケースです。無償で提供される、Salesforceの開発環境が二つあれば実現できますよと言うことです。みなさん、どうぞお使いください。
手順としてはこうなります。
- (接続される側)接続アプリケーションの作成
- (接続する側)認証プロバイダの作成
- (接続される側)接続アプリケーションの編集
- (接続する側)指定ログイン情報/外部データソースの作成
という手順になります。行ったり来たりになるのは理由があるからなんですΩ ΩΩ< な、なんだってー!!
1. (接続される側)接続アプリケーションの作成
まずは接続される側で接続アプリケーションを作成します。データアクセスを提供する側のSalesforceが、アクセス可能なユーザの制御や、利用できるAPIなどの制御を行うための設定です。まずこれがないと話になりません。
Salesforceの設定ページから操作します。クイック検索から「アプリケーション」とかで検索するか、アプリケーションカテゴリから、アプリケーションマネージャをクリックします。
おもむろに右上の新規接続アプリケーションをクリックしましょう。もう一つある新規Lightningアプリケーションではありません。あしからず。新規接続アプリケーションです。右側です。
新規接続アプリケーション作成時の入力項目
OAuthで接続される場合には、基本情報の入力必須項目以外にOAuth 設定の有効化が必要です。逆に言えば、そこさえ設定すれば良いです。
| 設定項目 | 設定する内容 |
|---|---|
| 接続アプリケーション名 | 人様が識別するための名前です。分かれば何でも良いです。識別できれば |
| API 参照名 | APIで参照するときに使う名前です。必ず英語です。アンスコも使えます。数字もいけた気がします |
| 取引先責任者 メール | この接続アプリを管理する人のメアド入れておきます。なんかあると通知されます |
| コールバック URL | 今は何でもいいです。https:// で始まる何か適当なURLをいれます |
| 選択した OAuth 範囲 | 利用させるOAuthのスコープを定義します。考えるのが面倒なテストの時はfullとrefresh_tokenがあれば良いです。refresh_tokenはfullに含まれないのでぜったに設定が必要です |
あとはひとまずデフォルトで良いです。なお、Salesforce Connectを利用する場合の最低限のOAuthスコープは、ここにもあるとおり次の四つです。
- Web 経由のデータへのアクセスを提供 (web)
- データへのアクセスと管理 (api)
- 基本情報へのアクセス (id, profile, email, address, phone)
- ユーザに代わっていつでも要求を実行 (refresh_token, offline_access)
refresh_token は重要です。ここまで入力したら「保存」します。サーバ上で設定が有効になるまで2〜10分待てと出てきますが、大抵すぐ使えます。たまにめっちゃ時間かかります。
設定に必要な項目のメモ(コピペする用)
あとで、認証プロバイダを作成するときに必要な次の項目をメモしておきます。どっかに一時的にペーストしておいときましょう。便利なことに、いずれもコピーボタンがついてます。素晴らしい。
- コンシューマ鍵
- コンシューマの秘密 (クリックしないと出てきません)
アクセスするユーザの追加
この「接続アプリケーション」を通じてアクセス可能なユーザを定義します。Manageボタンをクリックして「接続アプリケーションの詳細」が表示されたら｀ポリシーを編集`ボタンを押します。
この中の「OAuth ポリシー」ないの "許可されているユーザ" を "管理者が承認したユーザは事前承認済み" へ変更して保存します。
すると、下の方に「プロファイル」と「権限セット」という関連リストが追加されています。ここで脇目も振らず一心不乱に「プロファイルを管理する」ボタンをクリックします。次のような「アプリケーションプロファイルの割り当て」画面が表示されます。ここで、この接続アプリケーションを通じてアクセスさせたいユーザの持つプロファイルを選択します。一般的に専用のAPIユーザを準備したり、システム管理者を利用するでしょう。そのユーザに与えているプロファイルを選択します。そのプロファイルを持つユーザしかアクセスできません。
2. (接続する側)認証プロバイダの作成
さあて、今度は接続したい側、先ほど接続アプリケーションを作成したSalesforceの組織へアクセスする側の組織で設定します。Salesforceの設定画面から「認証プロバイダ」へアクセスします。設定の下、相当下、思ったよりも下にある「ID」カテゴリ内に「認証プロバイダ」があります。クイック検索した方が早いです。
そちらをクリックしたならば、すぐさま「新規」です。プロバイダタイプの設定画面のみがありますので、ここから「Salesforce」を選択します。ご覧いただければ分かるとおり、2020年12月現在、次の10のプロバイダに対応しています。これ以外のプロバイダを利用したい場合は、カスタム認証プロバイダを自作することも可能です。拙作[Salesforce] カスタム認証プロバイダの作り方 ~Client Credentials 編~もご覧いただけると幸いです。これみて気がつきましたが、Azureどこいった。
| 設定項目 | 設定内容 |
|---|---|
| 名前 | 人様が認識するために必要なだけの名前です。何でもいい |
| URL 接尾辞 | 承認に必要なさまざまなURLの最後に付与されるものですが、これもAPI識別子みたいなものです。ユニークな英語なら何でもどうぞ |
| コンシューマ鍵 | 先ほどコピペしろといったコンシューマ鍵です |
| コンシューマの秘密 | 同じくコンシューマの秘密です |
| 承認エンドポイント URL | 私のドメインが設定されているはずなので、それを指定する方が連携は容易です。デフォルトのままでもいけますが、ホスト名の後ろは必ず /services/oauth2/authorize です |
| トークンエンドポイント URL | 上記通りですが、こちらはホスト名以後は /services/oauth2/tokenに必ずなります |
| デフォルトの範囲 | 最重要ポイントです。ここで必ずrefresh_tokenが入らねばなりません。それ以外に必要なOAuthスコープを入れます |
ここまで設定できたら「保存」しますね。この後にも重要なポイントがあります。保存された後の画面にある コールバック URL の URLをコピペしてメモしておきます。下の方の Salesforce 設定内にありますよね。
デフォルトの範囲 について
Salesforce の認証プロバイダでは、デフォルトのOAuthスコープにrefresh_tokenの含まれないfullがハードコードされているようです。接続される側でいくらrefresh_tokenとfullを指定してあげても、refresh tokenを取得しません。なので必ず、OAuth でrefresh tokenが必要な場合には、ここでrefresh_tokenを指定しなければなりません。これは、あなた方の義務です。使命です。
なおrefresh_tokenを指定せず、デフォルトの空欄にしたまま、「外部データソース」や「指定ログイン情報」を設定するとどうなるか。認証自体は通るのですが、このようなメッセージが出てrefresh tokenが取得できなかったことが分かります。注意勧告程度のメッセージに見えますが、はっきり言って利用できません。refresh_tokenを定義しないと、この認証プロバイダは利用できないに等しいです。
検索用: 認証プロバイダが更新トークンを提供しませんでした。アクセストークンの有効期限が切れると、組織からこの外部データソースにアクセスできなくなります。
3. (接続される側)接続アプリケーションの編集
さて、またアクセスされる側に戻ります。先ほど適当に定義したコールバックURLを設定します。先ほど作成した「接続アプリケーション」を開き直して「編集」します。そして、先ほど雑に入力した「コールバック URL」部分を、認証プロバイダで定義された「コールバック URL」で上書きして保存してあげます。これで、受け入れ完了です。
4. (接続する側)指定ログイン情報/外部データソースの作成
あとは利用するアプリケーションに従って、認証プロバイダを利用するように定義します。主に「指定ログイン情報」と「外部データソース(Salesforce Connectを使用する場合)」でしょう。いずれも設定方法はだいたい同じです。いずれも設定を保存すると、Salesforce の認証画面が表示されますので、該当するユーザでログインしてあげれば設定完了です。やったぜ(๑•̀ㅂ•́)و✧
なお、ログイン先のURLを指定しなかったり、設定しなかったりしているような場合で、かつ https://login.salesforce.com からのログインが禁止されているとログインできません。URLを指定するか、認証時に「カスタムドメインを使用」として、ドメインを指定してログインしましょう。
指定ログイン情報の場合
| 設定名 | 設定内容 |
|---|---|
| 表示ラベル | なんでもいい(ry |
| 名前 | APIとは書いてませんが、これもAPIでアクセスする際の識別子なので、英語で指定します |
| URL | 接続する先のSalesforceのログインURLを指定します。login.salesforce.comでもいける気がするけど、私のドメインで設定したカスタムドメインの方が悔いがありません |
| ID 種別 |
ユーザとするとこのプロバイダを利用するユーザごとにログインするユーザを指定できます。指定ユーザにすると、ここで指定したユーザですべてのユーザは外部システムへアクセスするようになります |
| 認証プロトコル | 今回のケースでは、もちろんOAuth 2.0を指定します |
| 認証プロバイダ | さきほど作成した認証プロバイダにします。変な名前にすると、こんなことになるのでオススメしません |
| 範囲 | 認証プロバイダで指定した範囲をより狭めて利用したい場合にはここで定義します |
指定ログイン情報を設定すると、Apexでのコールアウトや外部サービスで利用できます。
外部データソースの場合
| 設定名 | 設定内容 |
|---|---|
| 外部データソース | なんでもいい(ry |
| 名前 | APIとは書いてませんが、これもAPIでアクセスする際の識別子なので、英語で指定します |
| 種別 | Salesforce Connect が利用する相手先の種類を指定します。今回のケースだとSalesforce Connect: クロス組織一択です |
| 接続先 | 対象となるSalesforceの環境に合わせて、Production や Sandbox を指定します。カスタムドメインを利用している場合には、このようにCustom URLにしてURLを定義するが吉です |
| URL |
Custom URLとした場合には、接続先のURLを指定します |
| APIバージョン | なるべく最新を。あえて昔のAPIを利用したい場合などには、ここで制御します |
| ID 種別 |
ユーザとするとこのプロバイダを利用するユーザごとにログインするユーザを指定できます。指定ユーザにすると、ここで指定したユーザですべてのユーザは外部システムへアクセスするようになります |
| 認証プロトコル | 今回のケースでは、もちろんOAuth 2.0を指定します |
| 認証プロバイダ | さきほど作成した認証プロバイダにします。変な名前にすると、こんなことになるのでオススメしません |
| 範囲 | 認証プロバイダで指定した範囲をより狭めて利用したい場合にはここで定義します |
外部データソースを設定すると、接続されている側のSalesforceのオブジェクトへアクセスが可能になります。保存した後、「検証して同期」ボタンをクリックすると「外部オブジェクト」として利用したいオブジェクトの選択画面になります。次のように「Account(取引先)」オブジェクトを選択して「同期」すると外部オブジェクトとして、相手先の取引先オブジェクトをカスタムオブジェクトのように利用できるようになります。
へぇ.