INSUITE EnterpriseとMicrosoft Azureを繋ぐ架け橋

〜 Orizuru: The super glue that brings Insuite and Microsoft Azure together. 〜

1. 特徴

AAD-Clientの特徴を以下に記載する

Single Sign On

OpenID Connect(以下OIDC)を利用してAzure Active Directory(以下AzureAD)とのシングルサインオン(以下SSO)を実現する。本モジュールによりINSUITEログインにAzureAD認証を利用することができる。

Microsoft Graph API

Microsoft Graph API(以下Graph API)を利用するためのアクセストークンを取得するためのゲートウェイ。SSO時に取得したGraphAPI用のアクセストークンを管理し、必要に応じてアクセストークンを取得するためのエンドポイントを提供する。

2. システム要件

2.1. アプリケーション要件

OS

RedHat 7.x or CentOS 7.x 以上

Web Server

Apache 2.4.x 以上

INSUITE

Ver 4.3.1 以上

OrizuruFW

Orizuru-Perl-1.4.0 以上
Orizuru-Javascript-1.1 以上

2.2. ネットワーク要件

  1. クライアント端末(PC or モバイル端末)からINSUITE、AAD-Client、Azure環境へそれぞれHTTP(s)によるネットワーク通信が可能であること。

  2. INSUITE APサーバからINSUITE 管理サーバに27017ポートで通信が可能であること。

3. 制限事項

  1. 本モジュールを適用後、INSUITE認証によるログインはできません。AzureAD認証のみとなります。[1]

  2. AzureADユーザとINSUITEユーザをマッピングするため、INSUITEユーザの外部id [2]。 をAzureADユーザのオブジェクトIDと一致させる必要があります。詳細は ユーザマッピングを参照下さい。

  3. ポートレットの予約語である "insuite_session_password"を利用することができません。[3]

  4. IMAPサーバに接続時、「認証にINSUITEのアカウントを使用する」設定をサポートしません。メールサーバ接続設定にメールアカウントとパスワードを設定してご利用ください。[3]

  5. 携帯サイト(/i)についてはAzureAD認証の対象外となり、通常のINSUITE認証となります。

4. 始めに

4.1. 基本構成

INSUITE APサーバ x 1台、管理サーバ x 1台で構成される環境の基本構成図は以下の通り。

基本構成
図 1. 基本構成
特別な注釈がない場合は、基本構成を前提としているものとする。

4.2. インストール

4.2.1. OrizuruFW

  1. Orizuru Framework for Perl のインストール

    • INSUITE 全AP・管理サーバでrootユーザで実行

      1. 弊社が発行する秘密鍵、公開鍵、証明書をご用意ください

      2. *.crt を client.crt、\*.key を client.key に名称を変更してください

      3. Orizuru Framework を使用するサーバに、/etc/ssl/orizuru ディレクトリを作成の上、2 で変更したファイルをアップロードしてください

      4. 下記コマンドを実行してください

        # yum install -y yum-utils
        # wget --certificate=/etc/ssl/orizuru/client.crt --private-key=/etc/ssl/orizuru/client.key https://orizuru.dreamarts.co.jp/yum/da-orizuru-repo.repo -O /etc/yum.repos.d/da-orizuru-repo.repo
        # yum install -y DA-Orizuru-Perl
    ※yum がご利用になれない場合は、直接 RPM での適用が必要となります。別途弊社までご連絡ください。
  2. Orizuru Framework for Javascriptのインストール

    • INSUITE 全AP・管理サーバでrootユーザで実行

      Orizuru Framework for Perlと同様にyumでインストール

      # yum install -y DA-Orizuru-JavaScript

4.2.2. INSUITE

  1. アカウント連携APIの有効化

    • INSUITE 管理サーバでrootユーザで実行

      # vi /home/DreamArts/data/custom/api.dat
      
        enable_cert_api=on (1)
      1 onになっていることを確認
  2. Custom.pmの編集

    • INSUITE 全APサーバでrootユーザで実行

      # vi /usr/local/share/perl/DA/Custom.pm
      
      (1)
      use DA::Plugin::CommonAPI::ExtAuth::AzureAD();
      
      sub auth_error {
              print DA::Plugin::CommonAPI::ExtAuth::AzureAD::redirect_login(@_);
              Apache::exit();
      }
      1 以下の内容を追加。
    設定の反映には、httpdサービスの再起動が必要です。詳細はサービスを確認してください。

4.2.3. Azure AD

  1. アプリの登録

    名前:INSUITE
    アプリケーションID:自動発行
    アプリケーション シークレット:「新しいパスワードを生成」
    プラットフォーム:
     暗黙的フローを許可する:チェック
     リダイレクトURL: https://[INSUITE_URL]/OAuth/AzureAD/auth/openid/return
     ログアウトURL: https://[INSUITE_URL]/OAuth/AzureAD/logout/pc
    委任されたアクセス許可:
     profile

4.2.4. AAD-Client

  1. セットアップ

    AAD-Client
    • INSUITE 全APサーバでrootユーザで実行

      # cd /home/DreamArts/Orizuru/JavaScript/Adapter/AAD-Client
      # bin/init
    MongoDB
    • INSUITE 管理サーバでrootユーザで実行

      1. インストール

        # cd /home/DreamArts/Orizuru/JavaScript/Adapter/AAD-Client
        # bin/initdb
      2. 設定

        # vi /etc/mongod.conf
        
        # network interfaces
        net:
          port: 27017
          bindIp: <PrivateIP or Host> (1)
        1 管理サーバのIPアドレス or ホスト名を指定する。127.0.0.1 or localhostは指定しないこと。
    設定の反映には、Mongodbサービスの再起動が必要です。詳細はサービスを確認してください。
  2. 設定

    • INSUITE 全APサーバでrootユーザで実行

      # cd /home/DreamArts/Orizuru/JavaScript/Adapter/AAD-Client/config
      # vi config.json
      基本設定
      {
        "insuiteUrl": "https://<INSUITE_URL>", (1)
        "insuiteRestApi": {
          "user": "insuite", (2)
          "pass": "**********"
        },
        "tenantID": "<Tenant_ID>", (3)
        "clientID": "<Client_ID>", (4)
        "clientSecret": "<Client_Secret>", (5)
        "mongoDB": {
          "databaseUri": "mongodb://<Admin_Server_HOST>/OIDCStrategy" (6)
        }
      }
      1 INSUITEのアクセスURLを指定する。
      2 data/custom/api.datの cert_api_user cert_api_pass の値を指定する。
      3 AzureADのディレクトリID(テナントID)を指定する。
      4 アプリの登録 で作成したアプリのアプリケーションIDを指定する。
      5 アプリの登録 でアプリに設定したシークレットを指定する。
      6 名前解決が可能なINSUITE管理サーバのホスト名(or FQDN)を指定します。default.jsonを参考に設定値を追加してください。
    設定の反映には、AAD-Clientサービスの再起動が必要です。詳細はサービスを確認してください。

4.3. サービス

各サービスはsystemd [4] にユニットとして登録され、OSの起動に合わせて自動で起動・停止される。

4.3.1. 起動・停止

手動によるサービス起動・停止方法について記載する。

  1. INSUITE

    • INSUITE 全AP・管理サーバでrootユーザで実行

      起動
      # systemctl start httpd.service
      停止
      # systemctl stop httpd.service
  2. AAD-Client

    • INSUITE 全APサーバでrootユーザで実行

      起動
      # systemctl start orizuru-aad-client.service
      停止
      # systemctl stop orizuru-aad-client.service
  3. MongoDB

    • INSUITE 管理サーバでrootユーザで実行

      起動
      # systemctl start mongod.service
      停止
      # systemctl stop mongod.service

5. 詳細

5.1. 構成要素

OIDCにおける各アプリケーション・サービスの役割を以下に記載する。

INSUITE

AAD-Clientと連携して、AzureADとOIDCを使用したSSOを実現。主にINSUITEセッション作成、INSUITEユーザ作成等、INSUITEに関する部分を実施する。

AzureAD

OpenID Provider (以下OP)として主に認証を担当。AD上のユーザ情報のResource Serverとして、GraphAPIをI/FとしたAPIサーバとしても動作する。

AAD-Client

Relying Party (以下RP)としてAzureAD(OP)に認証を要求するOAuth2.0 Clientとなる。INSUITEと連携し、INSUITEに対するSSOを実現。SSO時にAzureAD(OP)から取得したAD GrapAPIを利用するためのアクセストークンを管理し、アクセストークンエンドポイントの機能も持つ。

5.2. 認証

5.2.1. ログイン

INSUITEのログイン画面にアクセスすると、AzureADのログイン画面が表示され、そのままログインすることでAzureAD、INSUITEの両者のセッションが作成され、INSUITEのログイン後のTOPページが表示されます。

  • AzureADの有効なセッションが存在する場合は、INSUITEのログイン後のTOPページが表示されます。

  • INSUITEの各機能(ライブラリ等)のコンテンツURLからログインを実施した場合は、ログイン後のTOPページではなく各機能のコンテンツが表示されます。

5.2.2. ログアウト

INSUITEをログアウトすると、INSUITEのセッションが破棄されます。

  • INSUITEをログアウトしても、AzureADはログアウトされません。

  • シングルサインアウト(INSUITEのログアウトと同時にAzureADもログアウト)をする場合は、config.jsonのsingle_signoutパラメータを変更して下さい。詳細はconfig.jsonを参照して下さい。

5.2.3. セッション

セッションの有効期限についてはAzureAD、INSUITEの各アプリケーション・サービスの仕様に準拠します。

5.2.4. 処理シーケンス

OIDCの認証処理シーケンスを以下に記載する

ログイン
login
図 2. ログインシーケンス
ログアウト
logout
図 3. ログアウトシーケンス

5.3. アカウント連携

5.3.1. ユーザマッピング

AzureAD認証を実施するためには、AzureADユーザとINSUITEユーザが同一であることを保障するために、各ユーザの外部キーを一致させる必要があります。

ユーザ 外部キー

AzureAD

オブジェクトID(oid)

INSUITE

外部システムでのユニーク値(id)[5]

INSUITEユーザの外部キーは2つのパラメータ(key, id)で構成されています[5]。idについては上記の通り。 keyについては一律固定値となり、config.jsondatalinkKey で指定した値と一致させる必要があります。

5.3.2. ユーザ作成

AzureADユーザと一致するINSUITEユーザが存在しない場合、認証時にINSUITEユーザを作成することができます。

config.jsoninsuiteUserAutoCreatedefault パラメータの内容も合わせて参照下さい。

5.4. エンドポイント

AAD-Clientのエンドポイントについて記載する

  • 認証を要求する

    GET /OAuth/AzureAD/login/{device}

    Parameters

    parameters detail

    device

    pc or sp

    Response

    HTTP Code

    302

    Header

    Location

    https://login.microsoftonline.com/~

  • ログアウトを要求する

    GET /OAuth/AzureAD/logout/{device}

    Parameters

    parameters detail

    device

    pc or sp

    Response

    HTTP Code

    302

    Header

    Location

    https://login.microsoftonline.com/common/oauth2/logout~

  • トークンの取得・検証

    AzureAD認証後のコールバックエンドポイント。AzureADから取得したIDトークンの検証やアクセストークンの所得を実施する。

    POST /OAuth/AzureAD/auth/openid/return

    Parameters

    name detail

    code

    認可コード

    id_token

    ユーザートークン

    state

    ステート

    session_state

    セッションステート

    Response

    HTTP Code

    302

    Header

    Location

    /pc/login

    Set-Cookie

    INSUITE-Enterprise=xxxx.xxxx; path=/;

    Set-Cookie

    INSUITE-Enterprise_user_lang=xx; path=/;

  • アクセストークンの取得

    AzureAD Graph API用のアクセストークンを取得する。

    GET /OAuth/AzureAD/token

    Headers

    name value

    Cookie

    INSUITE-Enterprise=xxxx.xxxx

    Response

    HTTP Code

    200

    Header

    Content-Type

    application/json

    Body

    {
       "access_token": "xxxxxxxxx",
       "expires_on": "xxxxxx"
    }

    アクセストークン利用例

    Graph APIで自分のプロファイルを取得する
    $.ajax({
        type: 'GET',
        dataType: 'json',
        url: 'https://<INSUITE_URL>/OAuth/AzureAD/token'
    }).then(function (token) {
        $.ajax({
            type: 'GET',
            dataType: 'json',
            url: 'https://graph.microsoft.com/v1.0/me/',
            headers: {
                Authorization: 'Bearer ' + token.access_token
            }
        }).done(function (profile) {
            console.log(profile)
        });
    });

5.5. 設定

5.5.1. INSUITE

AzureAD.conf

ファイルパス

/etc/httpd/pre_conf.d/AzureAD.conf

5.5.2. AAD-Client

config.json

ファイルパス

/home/DreamArts/Orizuru/JavaScript/Adapter/AAD-Client/config/config.json

パラメータ 内容 既定値

insuiteUrl

INSUITEへのアクセスURLを指定します

https://<INSUITE_URL>

insuiteRestApi

user

api.dat [5]cert_api_user の値を指定する。

insuite

pass

api.dat [5]cert_api_pass の値を指定する。

**********

tenantID

AzureADのディレクトリID(テナントID)を指定する。

<Tenant_ID>

clientID

アプリの登録 で作成したアプリのアプリケーションIDを指定する。

<Client_ID>

clientSecret

アプリの登録 でアプリに設定したシークレットを指定する。

<Client_Secret>

datalinkKey

INSUITEのユーザ外部キーを指定する

AzureAD

cookieName

変更する必要はありません。

INSUITE-Enterprise

loggingLevel

ログレベルを指定する。

error

default

sortLevel

ユーザ作成時のソートレベルを指定する。

10

userLang

INSUITEのデフォルト言語[5]を指定する。

ja

extMid

変更する必要はありません。

/{key}/member/{id}

extPrimaryGroup

INSUITEユーザ作成時のプリマリ所属組織の外部キーを指定する。デフォルトは組織TOP。

/sys/group/2000000

insuiteUserAutoCreate

AzureAD認証時にINSUITEユーザを作成するかどうかを指定する。

true

mongoDB

databaseUri

AAD-ClientからMongoDBへの接続情報を指定する。認証が必要な場合は、mongodb://[user]/[pass]@localhost/OIDCStrategy の形式で指定する。MongoDBの認証についてはAuthenticationを参照。

mongodb://localhost/OIDCStrategy

graph

url

Graph APIのエンドポイントのURLを指定する。

https://graph.microsoft.com/V1.0

scope

Graph APIで利用可能なスコープを指定する

["https://graph.microsoft.com/user.read"]

single_signout

シングルサインアウトの利用可否を指定する。true:利用する。false:利用しない。

false

config.json sample
{
  "insuiteUrl": "https://<INSUITE_URL>",
  "insuiteRestApi": {
    "user": "insuite",
    "pass": "**********"
  },
  "tenantID": "<Tenant_ID>",
  "clientID": "<Client_ID>",
  "clientSecret": "<Client_Secret>",
  "datalinkKey": "AzureAD",
  "cookieName": "INSUITE-Enterprise",
  "loggingLevel": "info",
  "default": {
    "sortLevel": 10,
    "userLang": "ja",
    "extMid": "/{key}/member/{id}",
    "extPrimaryGroup": "/sys/group/2000000"
  },
  "insuiteUserAutoCreate": true,
  "mongoDB": {
    "databaseUri": "mongodb://localhost/OIDCStrategy"
  },
  "graph": {
    "url": "https://graph.microsoft.com/v1.0",
    "scope": ["https://graph.microsoft.com/user.read"]
  },
  "single_signout": true
}

5.6. ログ

5.6.1. ログファイル

AAD-Clientのアプリケーションログをログファイルに出力する。

ファイルパス

/var/log/Orizure/AAD-Client.log

パーミッション

-rw-r—​r-- 1 www www

5.6.2. ログローテーション

logrotate [6] を利用してログのローテーションを実施する。

定義ファイル

/etc/logrotate.d/orizuru-aad-client

保存世代

30世代まで保存する

タイミング

毎日

  • ローテーション後のログファイル名はAAD-Client.log-yyyymmddとする。

  • 定義ファイルで指定していない設定値についてはlogratateの初期設定(/etc/logrotate.conf)に従う。例) compress ..etc

  • ローテーション時にログの出力が重なった場合、ログが出力されない瞬間が存在する可能性がある。本バージョンにおいては制限事項とする。

5.7. データベース

AAD-ClientはAzureADの情報をMongoDBに格納している。以下に詳細を記述する。

DB Name

OIDCStrategy

Authentication

MongoDBはデフォルトでAuthenticationが無効化されており、認証が必要な場合は、最低限以下の対応を実施する必要がある。

  1. MongoDBのAuthenticationを有効化

  2. MongoDBの管理ユーザの作成

  3. MongoDBの管理ユーザでOIDCStrategyにユーザを作成し、Role(readWrite)を付与

  4. AAD-Clientのconfig.jsonMongoDB.databaseUri にユーザの認証情報(ID/Pass)を追加

    • MongoDBのAuthenticationについては、MongoDBの公式ドキュメントのSecurity項目を参照。

Roles

readWrite以上のRoleが必要。

Collections

session情報をsessionsコレクション、認証済みユーザ情報をusersコレクションに格納。ドキュメントサンプルは以下の通り。

sessions
{
    "_id": "YiAod5QidOAHcWBAslrFRkwM4jZm7RZr",
    "session": "{\"cookie\":{\"originalMaxAge\":86400000,\"expires\":\"2018-12-19T09:13:22.019Z\",\"httpOnly\":true,\"path\":\"/\"},\"passport\":{\"user\":\"d36dba02-1989-4b7c-a391-xxxx\"}}",
    "expires": "2018-12-19T09:13:22.019Z"
}
users
{
    "_id": "5c18ba307c48a410d48badf7",
    "info": {
        "userPrincipalName": "t_yume@xxxx.onmicrosoft.com",
        "preferredLanguage": null,
        "mail": "t_yume@xxxx.onmicrosoft.com",
        "jobTitle": null,
        "surkana": "Yume",
        "givenKana": "Taro",
        "surname": "夢",
        "givenName": "太郎",
        "displayName": "夢 太郎"
    },
    "profile": {
        "_json": {
            "ver": "2.0",
            "uti": "i3UoyPqn1k-8_x",
            "tid": "111a9fdd-7ad0-4393-84b0-7c7c",
            "sub": "UJWQCvK5ykqlT3FO39CTpx0C76VdcBv_odo7",
            "preferred_username": "t_yume@xxxx.onmicrosoft.com",
            "oid": "d36dba02-1989-4b7c-a391-xxxx",
            "nonce": "t5Pi_Flwz7IvnQh",
            "name": "夢 太郎",
            "aio": "ATQAy/8JAAAA/Zi1hxibPsqiQPdnWRoJ+JOSf5ythp+5NN03",
            "exp": 1545127999,
            "nbf": 1545124099,
            "iat": 1545124099,
            "iss": "https://login.microsoftonline.com/111a9fdd-7ad0-4393-84b0-7c7c/v2.0",
            "aud": "ca1dcda0-c03a-4ea1-b662-0a"
        },
        "_raw": "{\"aud\":\"ca1dcda0-c03a-4ea1-b662-0a\",\"iss\":\"https://login.microsoftonline.com/111a9fdd-7ad0-4393-84b0-7c7c/v2.0\",\"iat\":1545124099,\"nbf\":1545124099,\"exp\":1545127999,\"aio\":\"ATQAy/8JAAAA/Zi1hxibPsqiQPdnWRoJ+JOSf5ythp+5NN03\",\"name\":\"夢 太郎\",\"nonce\":\"t5Pi_Flwz7IvnQh\",\"oid\":\"d36dba02-1989-4b7c-a391-xxxx\",\"preferred_username\":\"t_yume@xxxx.onmicrosoft.com\",\"sub\":\"UJWQCvK5ykqlT3FO39CTpx0C76VdcBv_odo\",\"tid\":\"111a9fdd-7ad0-4393-84b0-7c7c\",\"uti\":\"i3UoyPqn1k-8_x\",\"ver\":\"2.0\"}",
        "displayName": "夢 太郎",
        "oid": "d36dba02-1989-4b7c-a391-xxxx",
        "sub": "UJWQCvK5ykqlT3FO39CTpx0C76VdcBv_odo"
    },
    "refresh_token": "OAQABAAAAAAC5una0EUFgTIF8ElaxtWjTTi7IfTSVO_oeYbqCbYNoLoCVeuQtyKn4XngPJAgsoOygZmy8P_9SNhfA22pWtZHt7zI2P7yfDIztevOqg6K-Td4NV6WDmnAo3NXULwRdnnR8DNN2l430hBLMBXBqzTjUAbLgDyl_CzkRhTNQUYnK42XNJ433ZNehYTSQuUJkWLyZbK9HCa1_wI1NAgO8xa3Gl5I29wqAZCCFDiR9YyZVoNTaE1DIxeqnRpkji8CNvi21JR5GKxh7C4AT6-lDj9EnonxY_sk-4X28JnMCJEyImFfm9pqC6LQXfSYG2KSCLdIjywAaei7moPkVEDf3kdYLky",
    "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFDNXVuYTBFVUZnVElGOEVsYXh0V2pUODBDVlhlUmpkN25uakQzbXZwSWxHeVZCSTg0bTlFTVZXOW5RTGtLeEVHYXFjUnFaalJwdjdwd0Fib0tOeGxYUmxBZW5zUGdoNVNxQ2xDXzNpN2tlRXlBQSIsImFsZyI6IlJTMjU2IiwieDV0IjoibmJDd1cxMXczWGtCLXhVYVh3S1JTTGpNSEdRIiwia2lkIjoibmJDd1cxMXczWGtCLXhVYVh3S1JTTGpNSEdRIn0.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC8xMTFhOWZkZC03YWQwLTQzOTMtODRiMC",
    "sid": "1000023.c1owqz27WKiy0F2B9tf9yS10",
    "oid": "d36dba02-1989-4b7c-a391-xxxx",
    "__v": 0
}

1. 管理サーバへのログインは除く。
2. 外部keyはconfig.jsonで指定。
3. SSO環境でINSUTIEを利用する場合の制限事項。
4. systemdの詳細については各OSのドキュメントを参照。
5. INSUITE アドミニストレーションガイドを参照。
6. logrotateの詳細については各OSのドキュメントを参照。