最近、社内でCRMを活用しようという話が出てきて、その中でオープンソースかつ無料で利用できるSuiteCRMに目をつけていました。
ただ、SuiteCRMを社内に導入するにあたり、EntraIDによるSSOは必須要件だったのですが、公式ドキュメントにEntraIDを用いたSSOについてほとんど記載がなかったので、かなり苦労しました...
コミュニティを見てもEntraIDの設定方法をまとめているものはなかったので、覚書としてまとめておこうと思います。
使用するツール
前提条件
- SuiteCRMがSAML認証なしですでに起動できる状態になっていること。起動方法は以下のページを参照してください。
https://docs.suitecrm.com/8.x/admin/installation-guide/downloading-installing/ - SuiteCRM内に、EntraIDでログインしたいユーザーがすでに作成されていること (自動作成もできますが、そちらは公式ドキュメントを参照してください)
手順
1. SAML認証に使用するEnterprise Applicationを作成する
SAML認証を行うにあたり、Enterprise Applicationを作成する必要があります。作成方法は以下を参考にしてください。
ただ、上記はv7を前提にしているので、そのまま手順に従ってもうまくいきません。
1.2. Configure the new Applicationの部分を、以下のように読み替えてください。
SuiteCRM uses the same value for Entity ID, ACS URL and Sign On URL.
The value should be your SuiteCRM URL in the following format:
{CRM URL}/index.php?action=Login&module=Users #この行を
{CRM URL} #この行に読み替える
/index.php?action=Login&module=Usersの部分がいらなくなった感じですね。
2. SuiteCRMの.env.localの設定
v7ではSAML認証の設定はAdminメニューから行っていたのが、v8.7.0では、.env.localで指定するようになったんですね。
これ自体は設定項目の幅が広がったのでいいことっぽいんですが、ドキュメント通りにやっても全くうまくいかない...
ということで、EntraIDでSAML認証するには最低限以下の設定が必要でした。
###> SAML CONFIG ###
AUTH_TYPE=saml
# User mapping options
SAML_USERNAME_ATTRIBUTE=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
SAML_USE_ATTRIBUTE_FRIENDLY_NAME=false
# Connection options
SAML_IDP_ENTITY_ID=https://sts.windows.net/{tenantId}/
SAML_IDP_SSO_URL=https://login.microsoftonline.com/{tenantId}/saml2
SAML_IDP_SLO_URL=https://login.microsoftonline.com/{tenantId}/saml2
SAML_IDP_X509CERT='-----BEGIN CERTIFICATE-----
{証明書の本体}
-----END CERTIFICATE-----'
# Compression
SAML_COMPRESS_REQUESTS=true
ポイントとしては、以下の通りです
SAML_USERNAME_ATTRIBUTE
SSOでログインする際のユーザー名をどこからとってくるかを設定するプロパティです。
ここで指定しているhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameをどこから持ってきたかというと、Enterprise Application -> Single Sign-on -> SAML Certificate -> Federation Metadata XMLでダウンロードした中に記載されています。
どうやらこのXMLはSAML認証時に返されるレスポンスが定義されているようで、http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameを指定すると、DisplaynameがNameとなっている値が取得できるみたいです。
これらの値がどこで定義されているかというと、同じくEnterprise Application->Single sign-on->Attribute & Claimに定義されているようです。
この場合のNameは私のアプリではuser.userprincipalnameとなっていました。
SAML_USE_ATTRIBUTE_FRIENDLY_NAME
これはSAMLレスポンスのUriの代わりにFrindlyNameを使用するかを指定するプロパティです。
このプロパティはデフォルトでtrueになっているのですが、EntraIDはこの「FRIENDLY_NAME」とやらに対応していません。
対応していると先ほどのXMLファイルに「FriendlyName」という属性が付与されているみたいです。
なので、このプロパティはfalseにする必要があります。
(これに気付くのに数日かかった...)
SAML_COMPRESS_REQUESTS
SAML認証のリクエストを圧縮するかを指定するプロパティです。SAML認証のリクエストは二段階で加工することができて、一段階目はBase64でエンコード、二段階目はdeflateで圧縮です。
このプロパティはデフォルトでfalseになっていますが、EntraIDはこれをtrueにしないと以下のエラーが発生します。
3. 変更内容の反映
.env.localの編集が完了したら、./bin/console cache:clearを実行して設定内容の反映を行ってください。
まとめ
上記の設定が完了後にブラウザからSuiteCRMを開くと、EntraIDでのログインが行われるはずです。
認証後すぐにログアウト画面が表示される場合は、SAML_USERNAME_ATTRIBUTEやSAML_USE_ATTRIBUTE_FRIENDLY_NAMEあたりの設定がうまくいっていない可能性が高いので、見直してみてください。
EntraIDのSSO認証は需要が多いはずなので、公式ドキュメントで設定例としてあげておいてもらえると助かるんですけどね...