Slack OAuth
Slackを業務アセットとして接続すると、Slackのアカウント・ユーザーグループ・チャンネルをYESODから管理できます。接続に必要な準備と、管理できる範囲を説明します。
概要
Slackは、チームのコミュニケーションを支えるビジネス向けメッセージングプラットフォームです。チャンネルでの会話、ユーザー管理、ユーザーグループ、チャンネルへの参加管理などの機能を提供します。
| 参照先 | リンク |
|---|---|
| 公式HP | https://slack.com/intl/ja-jp/ |
| 公式ヘルプ | https://slack.com/intl/ja-jp/help |
| APIドキュメント | https://api.slack.com/ |
YESODの「SaaS接続」画面での表記は「Slack OAuth」です。この記事では、接続先サービスとしてのSlackを「Slack」、YESODの画面に出る接続先サービス名を「Slack OAuth」と書き分けます。
管理できること
| 機能 | 対応 |
|---|---|
| アカウント作成 | ○ |
| グループ付与 | ○ |
| ロール付与 | ○ |
| グループプッシュ | ○ |
接続方式は標準コネクタです。管理できる範囲は次のとおりです。
| 項目 | 内容 |
|---|---|
| アカウント管理 | アカウントの作成、有効化・無効化（削除に相当）、属性同期による属性更新 |
| グループ・チャンネルの管理 | 割当種別で設定します（「グループ」「チャンネル」） |
| グループプッシュ | YESODのグループをSlackのユーザーグループとして作成・更新・削除します |
アカウント管理には、SCIM 2.0のAPIを使います。
事前に必要なもの
機能によって必要なSlackのプランが違います。
- アカウント管理（SCIM 2.0のAPIによるアカウントの作成・更新・無効化）: Business+プラン以上が必要です
- ユーザーグループ（グループ付与・グループプッシュ）: 有料プラン（Proプラン以上）が必要です。Freeプランのワークスペースでは利用できません
接続するときに使うSlackのアカウントは、ワークスペースのオーナーまたは管理者である必要があります。アカウント管理に使うSCIM APIのトークンは、この権限を持つアカウントだけが発行できるためです。
接続する
Slack OAuthはOAuthで接続します。YESODの画面には、接続情報を入力する項目がありません。「SaaS接続」画面で「Slack OAuth」を選ぶとSlackの画面へ移り、そこで許可すると業務アセットが作成されます。
画面の遷移と、接続を途中で取りやめた場合の動作は、業務アセットを追加するを参照してください。
接続すると、次のスコープをYESODへ委譲します。
| スコープ | 用途 |
|---|---|
admin | SCIM APIの利用（アカウントの作成・更新・無効化） |
team:read | ワークスペース情報の取得 |
users:read / users:read.email | メンバーの一覧とメールアドレスの取得 |
users:write | プレゼンス設定（現行機能では未使用） |
usergroups:read / usergroups:write | ユーザーグループの取得・作成・更新・無効化（グループ付与・グループプッシュで使用） |
channels:read / channels:write | チャンネル一覧の取得・チャンネルメンバーの追加・削除 |
アカウントの作成
Slackでは通常、招待（Invite）によってユーザーを作成します。招待の動作（メールの送信、ユーザーが最初に入力する項目など）は、Slack側の設定に依存します。ユーザー種別（通常メンバー・ゲストなど）も、Slack側の仕様とプランに依存します。
同じメールアドレスのアカウントがSlackに存在するかどうかに応じて、次のように動作します。
| 条件 | 動作 |
|---|---|
| 同じメールアドレスのアカウントがSlackに存在しない | アカウントを新規作成します |
| 同じメールアドレスの有効なアカウントがSlackに存在する | そのアカウントの情報を更新します |
| 同じメールアドレスの無効なアカウントがSlackに存在する | そのアカウントを有効にして情報を更新します |
Slack側の仕様により、既存アカウントのパスワードの更新・リセットには対応していません。パスワードはアカウントの作成時だけ設定されます。パスワードを変更するときは、ユーザー自身がSlack上で変更してください。
アカウントの削除
Slackでは、削除ではなく**無効化（Deactivation）**として扱います。すでに無効化されているアカウントに対して削除のタスクを実行した場合も、成功として扱われます。
割当種別
| 割当種別 | タイプ | 割当項目 | 説明 |
|---|---|---|---|
| グループ | 複数のグループに所属させる | SlackのAPIから取得します | Slackのユーザーグループへの所属を管理します |
| チャンネル | 複数のグループに所属させる | SlackのAPIから取得します | パブリックチャンネルへの参加を管理します |
アーカイブ済みチャンネルとプライベートチャンネルは、取り込みの対象外です。割当の対象になるのはパブリックチャンネルだけです。
Slackのユーザーグループには、少なくとも1人のメンバーが必要です。対象のアカウントがユーザーグループの唯一のメンバーである場合、割当剥奪のタスクはエラーになります。ユーザーグループを削除するか、他のメンバーを追加してから再度実行してください。
ワークスペースの全メンバーが参加するgeneralチャンネルからは、メンバーを外せません。generalチャンネルに対する割当剥奪のタスクは成功として扱われますが、Slack上ではチャンネルにメンバーが残ります。
同期する項目
業務アセットの「アカウント設定」にある「同期する項目」で、YESODの項目をSlackの項目へ対応づけます。SlackはSCIM 2.0を利用したプロビジョニングに依存します。項目の詳細はProvisioning with SCIM 2.0を参照してください。
次は、アカウントの作成と属性同期で使える代表的なマッピング項目です。
| 指定可能key | 必須 | 説明 | デフォルトの式 | 公式ドキュメントのProfile Attribute | 公式ドキュメントのSCIM Attribute |
|---|---|---|---|---|---|
userName | ✅ | ユーザー名。一意。最大21文字。ピリオド.・アンダースコア_・ハイフン-をサポート。その他はアンダースコアに変換 | String.substringBefore(user.email, "@") | Username | userName |
emails[0].value | ✅ | メールアドレス。アカウント検索の識別キーとして使用されます | user.email | emails[0]['value'] | |
emails[0].primary | - | メールアドレスがプライマリーかどうか（設定メールアドレスが1つの場合は強制的にtrue） | true | - | - |
name.givenName | - | 名 | user.givenNameLocalPreferred | name | - |
name.familyName | - | 姓 | user.familyNameLocalPreferred | name | - |
name.honorificPrefix | - | 敬称 | - | Honorific Prefix | name.honorificPrefix |
nickName | - | ニックネーム | - | Nickname | nickName |
displayName | - | 最大80文字。ピリオド.・アンダースコア_・ハイフン-をサポート。その他はアンダースコアに変換 | - | Display Name | displayName, userName |
password | - | パスワード。アカウントの作成時だけ設定されます（更新時は送信されません） | Password.generate(12, 16, 1, 3, 1, 3) | - | password |
profileUrl | - | プロファイルURL。URL形式で入力しないとSlackのデフォルトのURLになります | - | Profile URL | profileUrl |
photos[0].value | - | アクセスできるURL、または画像データを含むデータURL（例: data:image/png;base64,...） | - | Profile Photo | photos[0]['values'] |
title | - | 役職など | - | Title | title |
timezone | - | タイムゾーン | - | Timezone | timezone |
locale | - | 地域 | - | Locale | locale |
preferredLanguage | - | ユーザーの言語 | - | Preferred Language | preferredLanguage |
phoneNumbers[0].value | - | 電話（携帯電話type: 'mobile'の指定方法はSlack側の仕様に依存します） | - | Phone | phoneNumbers[0]['values'] |
addresses[0].locality | - | 住所（市区町村） | - | City | addresses[primary]['locality'] |
addresses[0].country | - | 国 | - | Country | addresses[primary]['country'] |
addresses[0].postalCode | - | 郵便番号 | - | Zip Code | addresses[primary]['postalCode'] |
userType | - | ユーザーの種別 | - | UserType | userType |
roles[0].value | - | ロール | - | Roles | roles |
extension.employeeNumber | - | 社員番号 | - | Employee ID | enterprise.employeeNumber |
extension.costCenter | - | コストセンター | - | Cost Center | enterprise.costCenter |
extension.organization | - | 組織 | - | Organization | enterprise.organization |
extension.division | - | 事業部 | - | Division | enterprise.division |
extension.department | - | 組織 | - | Department | enterprise.department |
extension.manager.managerId | - | マネージャーID。他のアカウントのID（例: U06P83AJ3U3）を指定します。有効なIDでない場合はnullが入ります | - | Manager | enterprise.manager.managerId |
グループプッシュ
グループプッシュを使うと、YESODのグループをSlackのユーザーグループとして作成・更新・削除できます。対象になるのは、会社・組織・事業所・プロジェクト・動的グループです。グループプッシュそのものの説明は、グループプッシュとはを参照してください。
グループプッシュで作成・管理できるのはSlackのユーザーグループだけです。チャンネルはグループプッシュの対象外です。チャンネルへの割当は、割当種別を参照してください。
前提条件
| 項目 | 内容 |
|---|---|
| 対象の接続 | Slack OAuthの業務アセットだけが対象です。Slack Enterprise GridとSlack Enterprise Grid (ゲスト)は対象外です。この2つはワークスペースの割当だけを管理し、ユーザーグループを扱わないためです |
| Slackのプラン | ユーザーグループを使える有料プラン（Proプラン以上）が必要です。Freeプランでは利用できません |
| 権限・再接続 | 必要なスコープ（usergroups:read / usergroups:write）は既存の接続で取得済みです。再接続・再認可は不要です |
Enterprise Gridプランを利用している場合も、ユーザーグループのグループプッシュはSlack OAuthの業務アセットから利用できます。
グループの作成・更新
同じ名前のユーザーグループがSlackに存在するかどうか（無効化済みを含む）に応じて、次のように動作します。
| 条件 | 動作 |
|---|---|
| 同名のユーザーグループがSlackに存在しない | ユーザーグループを新規作成します。メンバーは0人で作成され、後続の割当タスクで追加されます |
| 同名の有効なユーザーグループがSlackに存在する | 既存のユーザーグループにリンクし、属性を上書き更新します |
| 同名の無効化済みユーザーグループがSlackに存在する | エラーになります |
同名の有効なユーザーグループがすでに存在する場合、**YESODが作成したものかどうかを確認せずに採用して更新します。**手動で作成したユーザーグループも対象になります。グループ名の生成ルール（属性式）を決めるときは、Slack上の既存のユーザーグループと名前が衝突しないかを確認してください。
Slackのユーザーグループは、無効化してもグループ名とメンション名を占有し続けます。そのため、同名では新規作成できません。エラーになった場合は、Slack側で該当のユーザーグループを有効化して名前を変更するか、YESOD側のグループ名を変更してから再度実行してください。
無効化済みのユーザーグループを、自動で再有効化して再利用することはありません。再有効化すると無効化前のメンバー構成が復元され、YESODの管理外のメンバーが残るためです。
グループの削除
Slackにはユーザーグループを完全に削除する機能がありません。そのため、グループ削除のタスクは、ユーザーグループの無効化として実行されます。
すでに無効化されている場合と、対象のユーザーグループがSlackに存在しない場合は、成功として扱われます。
グループの移動
Slackのユーザーグループには階層がありません。そのため、グループの移動はありません。YESOD側のグループの階層は、フラットに連携されます。
グループプッシュで同期する項目
「グループプッシュ」の中の「同期する項目」で設定します。
| 指定可能key | 必須 | 説明 | デフォルトの式 | 備考 |
|---|---|---|---|---|
name | ✅ | グループ名 | group.groupNameLocal | ユーザーグループ間で一意である必要があります |
handle | - | メンション名（@handleで使われる文字列） | - | チャンネル名・ユーザー名・他のユーザーグループと重複できません。文字種の制限はなく、日本語も設定できます |
description | - | グループの説明 | - | - |
Slackの管理画面からユーザーグループを作成するときはメンション名が必須ですが、API経由では未指定でも作成できます。そのため、YESODでは任意の項目としています。未設定の場合は、メンション名なしでユーザーグループが作成されます。
ユーザーグループのデフォルトチャンネル（メンバーが追加されたときに自動でチャンネルへ追加する設定）の同期には対応していません。チャンネルへの参加は、割当種別の「チャンネル」でアカウント単位に管理します。
グループの属性同期
連携済みのユーザーグループに対して、「同期する項目」に設定された値を反映します。
- 属性マッピングを設定した項目だけが更新されます。設定していない項目は、Slack側の既存の値がそのまま維持されます
- YESOD側でグループの名称などを変更した場合、連携済みのユーザーグループが更新されます。別のユーザーグループが新規に作られることはなく、同じユーザーグループの名前が変わります
主なエラーと対処
グループプッシュのタスクがエラーになった場合、「タスク実行ログ」に原因と対処方法が表示されます。主なエラーは次のとおりです。
| Slackのエラーコード | 表示されるメッセージ | 原因と対処 |
|---|---|---|
paid_teams_only / plan_upgrade_required | ユーザーグループはSlackの有料プランでのみ利用できます。接続先ワークスペースのプランを確認してください。 | 接続先のワークスペースがFreeプランです。有料プランへのアップグレードが必要です |
name_already_exists | 同名のユーザーグループが既に存在します。YESOD側のグループ名、またはグループ名（name）の属性マッピングを変更してください。 | リネーム先の名前が既存のユーザーグループと重複しています |
handle_already_exists | メンション名が既に使用されています（チャンネル名・ユーザー名とも重複できません）。メンション名（handle）の属性マッピングを変更してください。 | メンション名がワークスペース内のチャンネル名・ユーザー名・他のユーザーグループと重複しています |
bad_handle / forbidden_handle | メンション名に使用できない値です。メンション名（handle）の属性マッピングを変更してください。 | Slack側でメンション名が拒否されました。発生条件はSlack側で非公開です |
name_too_long | グループ名が長すぎます。グループ名（name）の属性マッピングの評価結果を短くしてください。 | グループ名がSlackで許容される長さを超えています |
description_too_long | グループの説明が長すぎます。説明（description）の属性マッピングの評価結果を短くしてください。 | グループの説明がSlackで許容される長さを超えています |
permission_denied | ユーザーグループの管理権限がありません。Slackワークスペースのユーザーグループを管理できるロールの設定を確認してください。 | ユーザーグループを管理する権限が不足しています |
上記以外のエラーコードの場合は、Slackから返されたエラーの内容がそのまま「タスク実行ログ」に表示されます。