OneLogin
OneLoginを業務アセットとして接続すると、OneLoginのユーザー・ロール・グループをYESODから管理できます。接続に必要な準備と、管理できる範囲を説明します。
概要
OneLoginは、クラウドベースのIDaaS／SSOプロバイダーです。ユーザー認証、シングルサインオン、アクセス権限の一元管理をクラウドで提供しており、企業の各種SaaSへのアクセスを統合的に管理できます。
| 参照先 | リンク |
|---|---|
| 公式HP | OneLogin |
| 開発者向けポータル | OneLogin Developers |
| APIドキュメント（v2） | REST APIドキュメント（v2） |
| APIドキュメント（v1） | REST APIドキュメント（v1） |
管理できること
接続方式は標準コネクタです。管理できる範囲は次のとおりです。
| 項目 | 内容 |
|---|---|
| アカウント管理 | アカウントの作成・削除（サスペンド）、属性同期による属性更新、パスワードの設定・リセット |
| ロール・グループの管理 | 割当の付与・剥奪 |
管理対象
アカウントとして、OneLoginの「ユーザー」を管理します。登録されているユーザーの一覧は、OneLogin管理コンソールの「Users」＞「Users」で確認できます。
割当として、次の2つを管理します。
- ロール: OneLoginの「Role」です。1ユーザーに複数付与できます
- グループ: OneLoginの「Group」です。1ユーザーにつき1つだけ付与できます
接続に使う情報
| 入力項目 | 必須 | 入力する内容 |
|---|---|---|
| 「サブドメイン」 | 必須 | OneLoginテナントのサブドメイン。テナントのURLがhttps://acme.onelogin.comの場合はacmeを入力します |
| 「クライアントID」 | 必須 | API Credential PairのClient ID。OneLogin管理コンソールの「Developers」＞「API Credentials」で新しいCredentialを作成すると発行されます |
| 「クライアントシークレット」 | 必須 | API Credential PairのClient Secret。Client IDと同時に発行されます。発行後は再表示できないため、発行時に必ず控えてください |
| 「マッピングの適用」 | 必須 | アカウントの作成・更新時に、OneLogin側の自動マッピングを実行するかどうかを選びます。既定は「有効（デフォルト）」です |
Client Secretは第三者へ共有せず、安全な場所で管理してください。
サブドメインは、OneLogin APIのベースURLを組み立てるために使います。OneLogin APIの仕様上、Client IDとClient Secretが正しければ、サブドメインに適当な値を入力しても動作する挙動が確認されています。ただし、今後OneLogin側の仕様が変わり、サブドメインの一致が厳密に検査されるようになると、通信を遮断されるおそれがあります。安定して運用するために、「サブドメイン」には必ず正しい値を入力してください。
接続の準備
OneLoginのAPIを利用するため、OAuth 2.0のClient Credentials Grantによるトークンを発行します。OneLogin管理コンソールでAPI Credentialを発行し、そのClient IDとClient SecretをYESODに入力します。
Client IDとClient Secretを作成する
-
管理者ロールを持つアカウントで、OneLogin管理コンソールを開きます。
-
「Developers」＞「API Credentials」＞「New Credential」を開きます。
-
任意の名前を入力します。 例:
YESOD Integration -
スコープに「Manage All」を設定します。
-
Credentialを作成します。 Client IDとClient Secretが表示されます。Client Secretはこのときしか表示されないため、必ず控えて保存してください。
必要な権限
接続に使うAPI Credentialには、「Manage All」スコープを選択してください。
| スコープ | 業務アセットでの動作 |
|---|---|
| Authentication Only | 使用できません |
| Read Users | 書き込みができません |
| Manage users | パスワードの再設定だけがエラーになります |
| Read All | 書き込みができません |
| Manage All | すべての操作ができます |
「Manage users」でも、パスワードの再設定以外の操作は動作します。制限を理解していれば、「Manage users」のままでも運用できます。
接続する
「業務アセット」画面から「SaaS接続」画面を開くまでの手順は、業務アセットを追加するを参照してください。
-
「SaaS接続」画面で「OneLogin」を選択します。 「OneLogin 接続」画面が表示されます。
-
「サブドメイン」「クライアントID」「クライアントシークレット」を入力します。
-
「マッピングの適用」を選択します。
-
「接続」ボタンをクリックします。 同期が完了すると、業務アセットが作成されます。
マッピングの適用
OneLoginには、ユーザーの属性などに応じてロールなどを自動で付与するMappings（マッピング）という仕組みがあります。業務アセットがアカウントを作成・更新すると、その直後にOneLogin側のMappingsが動作し、YESODが設定した値を上書きする場合があります。
この挙動は、接続に使う「マッピングの適用」で選べます。
| 選択肢 | 挙動 | 選ぶ目安 |
|---|---|---|
| 「有効（デフォルト）」 | OneLoginの自動マッピングを実行します | OneLoginのMappingsを併用しており、自動のルールを効かせたい場合 |
| 「無効」 | OneLoginの自動マッピングを実行しません | YESODで設定した値が、OneLoginの自動のルールで変わるのを避けたい場合 |
特別な要件がなければ、既定の「有効（デフォルト）」のままで問題ありません。OneLogin側のMappingsによってYESODの設定値が意図せず変わることを避けたい場合は、「無効」を選択してください。
ただし、OneLoginの管理画面から「Reapply All Mappings」を実行すると、設定されているMappingsがすべて適用されます。このように、YESODを介さずにマッピングが適用されることもあります。
アカウントの作成
アカウント作成のタスクを実行すると、同じメールアドレス（email）のアカウントがOneLoginにあるかどうかで、作成・更新・再有効化の動作が変わります。
| 条件 | 動作 |
|---|---|
| 同じメールアドレスのアカウントがOneLoginに存在しない | アカウントを新規作成します |
同じメールアドレスのアクティブなアカウント（status=1）がOneLoginに存在する | そのアカウントの情報を更新します |
同じメールアドレスのサスペンド済みアカウント（status=2）がOneLoginに存在する | そのアカウントを有効化（status=1）してから情報を更新します |
同じメールアドレスのロック済みアカウント（status=3）がOneLoginに存在する | アンロック後、有効化（status=1）して情報を更新します |
パスワードの設定
アカウント作成時のパスワードの設定に対応しています。「同期する項目」でuser.passwordを設定すると、アカウントの作成時にそのパスワードが設定されます。
既存アカウントのパスワードリセット（パスワードの再発行）にも対応しています。
SSOでの運用などでuser.passwordの同期をOFFにしている場合、パスワードリセットのタスクは失敗します。リセット時に発行するパスワードを生成できないためです。パスワードリセットを使う運用では、user.passwordの同期を有効にしておいてください。
招待メールの送信
OneLogin APIで作成したアカウントには、OneLoginの標準では招待メールが自動送信されません。アカウントの作成時に招待メール（パスワード設定リンク）を送信するかどうかは、「同期する項目」で選べます。
user.sendEmailにtrueを設定すると、アカウントの作成が成功した後で招待メールが送信されます- 既定ではマッピングが設定されていないため、招待メールは送信されません
- SSOでの運用などで招待メールが不要な場合は、この項目を設定しないままでかまいません
招待メールを送信しない運用では、ユーザーが初めてOneLoginを使うための案内が別途必要です。次のどちらかで案内してください。
- アカウントの作成時にパスワードを設定し、ユーザーへ手動で連絡する
- OneLogin管理コンソールから招待リンクを送信する
招待リンクは、OneLogin管理コンソールの「Users」＞「Users」で対象のユーザーを開いて送信します。操作は「More Actions」＞「Send Invitation」です。
アカウントの削除
アカウント削除のタスクを実行すると、OneLogin上のアカウントはサスペンド（停止）（status=2）になります。
OneLoginには、API経由でユーザーを完全に削除する機能（DELETE /api/2/users/:id）もあります。ただし、削除したユーザーは復元できず、削除後は管理コンソール上にも表示されなくなります。意図せず情報を失うリスクが高いため、YESODからの物理削除には対応していません。
割当種別
| 割当種別名 | タイプ | 割当項目の例 | 備考 |
|---|---|---|---|
| ロール | 複数のグループに所属させる | Default／Admin／Engineeringなど | OneLogin管理コンソールの「Users」＞「Roles」で確認できます。利用者が登録して使う値のため、環境によって項目は異なります。APIで作成・削除できます |
| グループ | 優先度の高いグループに所属させる | Sales／Engineering／HRなど | OneLogin管理コンソールの「Users」＞「Groups」で確認できます。OneLogin側で事前に作成する必要があります（API経由での作成・編集・削除はできません） |
グループは1ユーザーにつき1つだけです。別のグループを割り当てると、所属が移動します。
グループの割当項目には、OneLoginから取り込んだグループのほかにNoneが並びます。Noneを割り当てると、アカウントはどのグループにも所属しない状態になります。
同期する項目
業務アセットの「アカウント設定」にある「同期する項目」で、YESODの項目をOneLoginの項目へ対応づけます。
| 必須 | 属性名 | key | 型 | デフォルトの式 | 備考 |
|---|---|---|---|---|---|
| ✅ | メールアドレス | user.email | 文字列 | user.email | アカウント検索の識別キーとして使用されます |
| - | ユーザー名 | user.username | 文字列 | user.email | OneLoginの認証に使えるユーザー名です |
| ✅ | 名 | user.firstname | 文字列 | user.givenNameLocalPreferred | ユーザーの名。値が空でもアカウントの作成は成功します |
| ✅ | 姓 | user.lastname | 文字列 | user.familyNameLocalPreferred | ユーザーの姓。値が空でもアカウントの作成は成功します |
| - | 役職 | user.title | 文字列 | - | OneLoginの「Job Title」 |
| - | 組織 | user.department | 文字列 | - | OneLoginの「Department」 |
| - | 会社 | user.company | 文字列 | - | OneLoginの「Company」 |
| - | 電話番号 | user.phone | 文字列 | - | E.164形式（例: +81901234567） |
| - | 外部ID | user.external_id | 文字列 | - | 他システムとの連携に使う任意のID |
| - | コメント | user.comment | 文字列 | - | OneLoginの管理者向けのフリーテキストのメモ |
| - | マネージャー | user.manager_user_id | 数値 | - | OneLogin上のマネージャーのユーザーID |
| - | ロケール | user.preferred_locale_code | 文字列 | - | 2文字のロケールコード（例: ja、en） |
| - | 招待メール送信 | user.sendEmail | 真偽値 | - | アカウントの作成時に招待メール（パスワード設定リンク）を送信するかどうか |
メールアドレスとユーザー名は、どちらかがあればアカウントを作成できます。ただし、ユーザー情報を取得するときにメールアドレスを使うことがあるため、user.emailには必ず値を入れてください。
カスタム属性
OneLoginには、テナントごとのカスタム属性（Custom Attributes）を定義する機能があります。
カスタム属性は、事前にOneLogin管理コンソールで定義する必要があります。定義の方法は、OneLoginのCustom User Fieldsの設定方法を参照してください。
定義したカスタム属性のキー（shortname）を使うと、「同期する項目」にマッピングを追加できます。書式はuser.custom_attributes.<shortname>です。
例えば、OneLogin側でemployee_codeというカスタム属性を定義しているとします。この場合はuser.custom_attributes.employee_codeをuser.employeeNumberなどに対応づけます。
カスタム属性は部分マージで更新されます。指定したキーだけが更新され、指定しなかったキーは既存の値を保持します。
カスタム属性を対応づける前に、OneLogin管理コンソールでそのshortnameを持つフィールドを作成してください。作成する場所は「Users」＞「Custom User Fields」です。作成していないカスタム属性を対応づけると、API呼び出し時にエラー（422）になります。エラーメッセージには、該当するキー名が含まれます。
同期対象外の項目
OneLoginのユーザーには、API上で書き込めるフィールドがほかにもあります。次の項目は、YESODからの同期の対象外です。
| 項目 | OneLoginフィールド | 理由 |
|---|---|---|
| 承認段階 | state | アカウントの承認の進み具合を表すため |
| ディレクトリ／IdP連携ID | directory_id / trusted_idp_id | ディレクトリ・IdP連携の内部IDのため |
| AD連携属性 | samaccountname / member_of / userprincipalname / distinguished_name / manager_ad_id | Active Directory由来の属性のため（AD連携側で管理） |
| OpenID表示名 | openid_name | 利用ケースが限定的なため |
| 認証の連続失敗回数 | invalid_login_attempts | OneLoginが管理するセキュリティカウンターのため |
これらは主にディレクトリ連携（Active Directory / LDAP）や、OneLogin内部・セキュリティ機構が管理する領域です。YESODから書き込むと、ディレクトリ同期や内部の状態と競合するおそれがあります。これらの値を変更するときは、OneLogin管理コンソールか、各ディレクトリ連携側で操作してください。
グループプッシュ
グループプッシュには対応していません。OneLoginのGroup APIには取得の操作しかなく、作成・更新・削除ができないためです。YESODのグループ階層をOneLoginへプッシュできません。
一括実行
複数件のタスクをまとめて実行する一括実行には対応していません。
制限事項
レートリミット
OneLoginのAPIには、アカウント単位で1時間あたり5,000回の呼び出し制限があります。API Credentialを複数発行していても、テナント全体で同じ上限を共有します。
上限に達すると429 Too Many Requestsが返り、エラーになります。YESODは指数バックオフで最大5回まで再試行しますが、それでも回復しない場合はタスクが失敗します。
現在の残量は、OneLogin APIのGET /auth/rate_limitで確認できます。各APIの応答には、残量を示すヘッダーが含まれません。
Privilege
OneLoginのPrivilege機能には対応していません。業務アセットが扱うのは、RoleとGroupだけです。Privilegeは、Delegated Administrationのサブスクリプションで利用できる、v1 APIの細かい権限です。
Privilege APIは、Delegated Administrationを含む契約のテナントでのみ利用できます。契約がないテナントではAPI自体が拒否されるため、契約状況に依存しない機能としては提供していません。