UAAはマルチテナントID管理サービスであり、Cloud Foundryで使用されますが、スタンドアロンのOAuth2サーバーとしても利用可能です。主な役割はOAuth2プロバイダーであり、Cloud Foundryユーザーに代わって動作するクライアントアプリケーションが使用するトークンを発行します。また、Cloud Foundryの認証情報を使用してユーザーを認証したり、それらの認証情報（または他のもの）を使用してSSOサービスとして機能することもできます。ユーザーアカウント管理およびOAuth2クライアント登録のためのエンドポイントに加え、さまざまな管理機能も備えています。

関連情報

• トークン: トークン、スコープ、権限に関する注意事項
• 技術フォーラム: cf-dev メーリングリスト
• ドキュメント: docs/
• APIドキュメント: UAA-APIs.rst
• 仕様: OAuth 2.0 認証フレームワーク
• LDAP: UAA LDAP統合

クイックスタート

必要条件:

• Java 8

これが動作すれば準備は完了です:

$ git clone git://github.com/cloudfoundry/uaa.git
$ cd uaa
$ ./gradlew run

すべてのアプリは同じポート(8080)上で動作し、/uaa, /app, /api としてアクセスできます。

UAAはuaa.logというファイルにログを出力します。次のコマンドで見つけることができます:-

$ sudo find / -name uaa.log

以下のような場所に見つかるはずです:-

/private/var/folders/7v/518b18d97_3f4c8fzxphy6f8zcm51c/T/cargo/conf/logs/

Cloud Foundryへのデプロイ

アプリをビルドしてCloud Foundryにプッシュすることもできます。例えば、推奨する方法はマニフェストファイルを使用することですが、すべてをコマンドラインで行うこともできます。

$ ./gradlew :cloudfoundry-identity-uaa:war
$ cf push myuaa --no-start -m 512M -p uaa/build/libs/cloudfoundry-identity-uaa-2.3.2-SNAPSHOT.war 
$ cf set-env myuaa SPRING_PROFILES_ACTIVE default,hsqldb
$ cf set-env myuaa UAA_URL http://myuaa.<domain>
$ cf set-env myuaa LOGIN_URL http://myuaa.<domain>
$ cf set-env myuaa JBP_CONFIG_SPRING_AUTO_RECONFIGURATION '[enabled: false]'
$ cf set-env myuaa JBP_CONFIG_TOMCAT '{tomcat: { version: 7.0.+ }}'
$ cf start myuaa

上記の手順で、次の項目を置き換えてください：

• myuaa を一意のアプリケーション名に
• 2.3.2-SNAPSHOT をビルドの適切なバージョンラベルに
• <domain> はアプリのドメインです。将来はシステム環境から解析される予定です。
• また、環境変数UAA_CONFIG_YAMLに完全な設定yamlを含む構成マニフェストを提供することもできます。

ローカルサーバーでのコマンドライン使用例

まず、上記のようにUAAサーバーを実行します：

$ ./gradlew run

次に、別のターミナルを開き、プロジェクトのベースディレクトリから、ログインエンドポイントにシステムについて問い合わせます：

$ curl -H "Accept: application/json" localhost:8080/uaa/login
{
  "timestamp":"2012-03-28T18:25:49+0100",
  "commit_id":"111274e",
  "prompts":{"username":["text","Username"],
    "password":["password","Password"]
  }
}

次に、UAA Ruby gemを使用してログインを試すことができます。Ruby 1.9が必要です。その後、

$ gem install cf-uaac
$ uaac target http://localhost:8080/uaa
$ uaac token get marissa koala

（またはユーザー名/パスワードを省略してプロンプトを受け取ります）。

これにより、OAuth2 implicit grantを使用してサーバーからアクセストークンを認証・取得します。これは、CFのようなクライアントが使用するアプローチと同様です。トークンは ~/.uaac.yml に保存されるので、そのファイルからアクセストークンを取得して cf ターゲットに使用するか、上記のログインコマンドラインで --verbose を使用してコンソールに出力されたトークンを確認してください。

次に、リソースサーバーとしてログインし、トークンの詳細を取得できます：

$ uaac target http://localhost:8080/uaa
$ uaac token decode

標準出力に自分のユーザー名と元のトークン付与のクライアントIDが表示されます。例：

  exp: 1355348409
  user_name: marissa
  scope: cloud_controller.read openid password.write scim.userids tokens.read tokens.write
  email: [email protected]
  aud: scim tokens openid cloud_controller password
  jti: ea2fac72-3f51-4c8f-a7a6-5ffc117af542
  user_id: ba14fea0-9d87-4f0c-b59e-32aaa8eb1434
  client_id: cf

デフォルトのMySQLおよびPostgreSQL設定に対するローカルシステムの実行（およびFlywayマイグレーションスクリプト情報）

$ ./gradlew -Dspring.profiles.active=default,mysql run

このコマンドは、デフォルト設定でアクセス可能なMySQLデータベースがあることを前提とし、以下のJDBC設定に応答します。

driver = 'org.mariadb.jdbc.Driver'
url = 'jdbc:mysql://localhost:3306/uaa'
user = 'root'
password = 'changeme'
schemas = ['uaa']

同様に、次のコマンドを実行すると

$ ./gradlew -Dspring.profiles.active=default,postgresql run

次の設定が使用されます：

driver = 'org.postgresql.Driver'
url = 'jdbc:postgresql:uaa'
user = 'root'
password = 'changeme'

これらの設定は、Gradle統合のために2か所に重複しています。Spring XML設定ファイルにデフォルトとして定義されており、メインのbuild.gradleファイルにも定義されています。Gradleビルドファイルにこれらがある理由は、Gradleが常にUAAアプリケーションを起動する前にflywayCleanタスクを実行するためです。データベースをクリーンアップしたくない場合は、コマンドラインで変数 -Dflyway.clean=false を定義できます。これにより、gradleスクリプト内のflywayCleanタスクが無効になります。flywayCleanを無効にする別の方法は、コマンドラインでSpringプロファイルを指定せず、uaa.ymlおよびlogin.ymlファイルでプロファイルを設定することです。

run.pivotal.ioでのコマンドライン使用例

同じコマンドライン例はrun.pivotal.ioで実行されているUAAでも動作するはずです（クライアントシークレットがないためトークンデコード部分は除く）。この場合、ローカルのUAAサーバーを実行する必要はないため、外部のログインエンドポイントにシステムについて問い合わせるだけです：

$ curl -H "Accept: application/json" login.run.pivotal.io
{
  "prompts":{"username":["text","Username"],
    "password":["password","Password"]
  }
}

その後、UAA Ruby gemを使用してログインを試すことができます。Ruby 1.9が必要です。その後、

$ gem install cf-uaac
$ uaac target uaa.run.pivotal.io
$ uaac token get [yourusername] [yourpassword]

（またはユーザー名/パスワードを省略してプロンプトを受け取ります）。

これにより、OAuth2 implicit grantを使用してサーバーからアクセストークンを認証・取得します。これはCFのようなクライアントが使用するものと同じです。

統合テスト

次のコマンドで統合テストを実行できます

$ ./gradlew integrationTest

統合テストはローカルのApache Tomcatインスタンスで実行されているUAAサーバーに対して実行されるため、例えばサービスURLはデフォルトで http://localhost:8080/uaa に設定されます。

CLOUD_FOUNDRY_CONFIG_PATH を指定して、URLを変更できる uaa.yml を読み込み、（必要に応じて）サーバー実行のコンテキストルートを設定できます（詳細は以下参照）。

カスタムYAML設定

実行時パラメータを変更するには、uaa.yml を提供できます。例：

$ cat > /tmp/config/uaa.yml
uaa:
  host: uaa.appcloud21.dev.mozycloud
  test:
    username: [email protected] # defaults to [email protected]
    password: changeme
    email: [email protected]

次に、uaa/uaa ディレクトリから

$ CLOUD_FOUNDRY_CONFIG_PATH=/tmp/config ./gradlew test

Webアプリは起動時に以下の場所からYamlコンテンツを探します（後のエントリが前のものを上書きします）。

classpath:uaa.yml
file:${CLOUD_FOUNDRY_CONFIG_PATH}/uaa.yml
file:${UAA_CONFIG_FILE}
${UAA_CONFIG_URL}
System.getEnv('UAA_CONFIG_YAML') -> 環境変数。設定されている場合は有効なYamlを含む必要があります。

例えば、UAAをCloud Foundryアプリケーションとしてデプロイするには、以下のようなアプリケーションマニフェストを提供できます。

---
  applications:
  - name: standalone-uaa-cf-war
    memory: 512M
    instances: 1
    host: standalone-uaa
    path: cloudfoundry-identity-uaa-3.0.0-SNAPSHOT.war
    env:
      JBP_CONFIG_SPRING_AUTO_RECONFIGURATION: '[enabled: false]'
      JBP_CONFIG_TOMCAT: '{tomcat: { version: 7.0.+ }}'
      SPRING_PROFILES_ACTIVE: hsqldb,default
      UAA_CONFIG_YAML: |
        uaa.url: http://standalone-uaa.cfapps.io
        login.url: http://standalone-uaa.cfapps.io
        smtp:
          host: mail.server.host
          port: 3535

または、代替として、set-envコマンドを使用して環境変数にYAML設定を文字列として設定します。

cf set-env sample-uaa-cf-war UAA_CONFIG_YAML '{ uaa.url: http://standalone-uaa.myapp.com, login.url: http://standalone-uaa.myapp.com, smtp: { host: mail.server.host, port: 3535 } }'

さらに、UAAによって読み取られる単純型プロパティは、システム環境変数自体として完全に展開して読み取ることもできます。uaa.url が UAA_URL という環境変数に変換される方法に注目してください。

---
  applications:
  - name: standalone-uaa-cf-war
    memory: 512M
    instances: 1
    host: standalone-uaa
    path: cloudfoundry-identity-uaa-3.0.0-SNAPSHOT.war
    env:
      JBP_CONFIG_SPRING_AUTO_RECONFIGURATION: '[enabled: false]'
      JBP_CONFIG_TOMCAT: '{tomcat: { version: 7.0.+ }}'
      SPRING_PROFILES_ACTIVE: hsqldb,default
      UAA_URL: http://standalone-uaa.cfapps.io
      LOGIN_URL: http://standalone-uaa.cfapps.io
      UAA_CONFIG_YAML: |
        smtp:
          host: mail.server.host
          port: 3535

Gradleを使用したPostgreSQLまたはMySQLでのテスト

デフォルトのUAA単体テスト（./gradlew test integrationTest）はhsqldbを使用します。

PostgreSQLを使用して単体テストを実行するには：

$ ./gradlew -Dspring.profiles.active=default,postgresql test integrationTest

オプションで、Springプロファイルは uaa.yml ファイルで設定できます。

$ echo "spring_profiles: default,postgresql" > src/main/resources/uaa.yml

MySQLを使用して単体テストを実行するには：

$ ./gradlew -Dspring.profiles.active=default,mysql test integrationTest

commonモジュールとscimモジュールのデータベース設定は、Spring XML設定ファイルでデフォルト化されています。uaa.yml で設定することで変更できます。

デフォルトは次のとおりです。

PostgreSQL: User: root Password: changeme Database: uaa Host: localhost Port: 5432
MySQL:      User: root Password: changeme Database: uaa Host: localhost Port: 3306

プロジェクト一覧

実際にはここにはいくつかのプロジェクトがあります。メインのuaaサーバーアプリケーション、クライアントライブラリ、およびいくつかのサンプルです：

1. uaa 簡単にデプロイできるWARプロジェクト

2. server UAAのREST API（SCIMを含む）とUIの実装を含むJARプロジェクト

3. model クライアントライブラリとサーバーの両方で使用されるJARプロジェクト

4. client-lib JavaクライアントAPIを提供するJARプロジェクト

5. api (サンプル) デプロイされたアプリのモックリストを返すOAuth2リソースサービス

6. app (サンプル) 上記の両方を使用するユーザーアプリケーション

CloudFoundryの用語では

• uaa は認証サービスと、バックエンドサービスおよびアプリへの認証済み委任（OAuth2アクセストークンの発行による）を提供します。

• api は、他のアプリケーションがリソース所有者（エンドユーザー）に代わってアクセスしたいリソースを提供するサービスです。

• app は、シングルサインオンと、ユーザーに代わって api サービスにアクセスする必要があるWebアプリです。

コードの構成

プロジェクトは水平レイヤー（client、model、serverなど）に編成されています。これらのプロジェクト内では、Javaパッケージは内部サービス（zones、providers、clientsなど）を中心に垂直に編成されています。

UAAサーバー

認証サービスはuaaです。これはシンプルなSpring MVC Webアプリです。Tomcatやお好みのコンテナに通常通りデプロイするか、./gradlew runを実行してソースツリーのuaaディレクトリから直接実行します。Gradleで実行すると、ポート8080でリッスンし、URLはhttp://localhost:8080/uaaになります。

UAAサーバーはUAA-APIsドキュメントで定義されたAPIをサポートしています。要約すると次のとおりです：

1. OAuth2の/oauth/authorizeおよび/oauth/tokenエンドポイント

2. 必要なログインプロンプトを照会するための/login_infoエンドポイント

3. リソースサーバーがOAuth2クライアントから送信されたアクセストークンに関する情報を取得できるようにする/check_tokenエンドポイント

4. リソースサーバーがトークン署名を検証するための検証キーを取得できるようにする/token_keyエンドポイント

5. SCIMユーザープロビジョニングエンドポイント

6. 認証/userinfoをサポートするOpenID Connectエンドポイント。部分的なOpenIDサポート。

コマンドラインクライアントは、資格情報を直接/oauth/authorizeエンドポイントに送信して認証を実行できます（UAA-APIドキュメントに説明あり）。クライアントがJavaの場合、Spring Security OAuthにImplicitAccessTokenProviderがあり、面倒な処理を行います。

デフォルトでは、uaaはコンテキストルート/uaaで起動します。

ユースケース

1. 認証

   root@kitploit:~

    GET /login
   

   基本的なフォームログインインターフェース。

2. OAuth2トークン付与の承認

   root@kitploit:~

    GET /oauth/authorize?client_id=app&response_type=code...
   

   標準のOAuth2認証エンドポイント。

3. アクセストークンの取得

   root@kitploit:~

    POST /oauth/token
   

   標準のOAuth2認証エンドポイント。

設定

アプリケーションにはuaa.ymlとlogin.ymlの2つの設定ファイルがあり、Spring XMLのプレースホルダーにデフォルト値を提供します。XML内で${placeholder.name}が見られた場合は、同じ名前のシステムプロパティ（JVMに-Dで指定）を提供するか、カスタムのuaa.ymlまたはlogin.yml（前述の通り）で上書きできます。

uaa.ymlとlogin.ymlは起動時に1つの設定にマージされます。

設定ファイル内のすべてのパスワードとクライアントシークレットは平文ですが、BCryptで暗号化されてUAAデータベースに挿入されます。

将来は、平文パスワードを指定しなくて済むように、bcrypt形式でパスワードを提供できるようになる予定です。

ユーザーアカウントデータ

デフォルトでは、メモリ内のRDBMSユーザーストアを使用し、1人のテストユーザーがあらかじめ入力されています：marissaのパスワードはkoalaです。

ユーザーデータにPostgreSQLを使用するには、Springプロファイルpostgresqlを有効にします。

アクティブなプロファイルはuaa.ymlで次のように設定できます。

spring_profiles: postgresql,default

またはコマンドラインでPostgreSQLを指定します：

 $ ./gradlew -Dspring.profiles.active=default,postgresql run
 

APIサンプルアプリケーション

UAAには2つのサンプルアプリケーションが含まれています。/apiと/appです。uaaルートディレクトリから./gradlew runを使用して実行します。3つのアプリ（/uaa、/api、/app）が同時にデプロイされます。

Appサンプルアプリケーション

これは、認証にOpenID Connect（SSO）を、アクセス権限付与にOAuth2を使用するユーザーインターフェースアプリ（主にブラウザ向け）です。認証サービスで認証し、その後APIサービスのリソースにアクセスします。uaaルートディレクトリから./gradlew runで実行します。

このアプリケーションは、UAAサーバーとログインアプリケーションの場所（および有無）に応じて、複数の異なるプロファイルで動作できます。デフォルトでは、localhost:8080/uaaのUAAを探しますが、UAA_PROFILEという環境変数（またはシステムプロパティ）を設定することで変更できます。アプリケーションのソースコード（samples/app/src/main/resources）には、それらのサーバーの可能性のある異なる場所が事前設定された複数のプロパティファイルがあります。これらはすべてapplication-<UAA_PROFILE>.propertiesという形式で、命名規則として、UAA_PROFILEはlocalhostデプロイメントの場合はlocal、vcap.meデプロイメントの場合はvcap、ステージングデプロイメント（VMware VPN内）の場合はstagingなどです。プロファイル名は二重になっている場合があります（例：ログインサーバーがUAAサーバーとは異なる場所にある場合はlocal-vcap）。

ユースケース

1. すべてのアプリを表示

   root@kitploit:~

    GET /app/apps
   

   ブラウザは一連の認証とアクセス権限付与の手順（ある時点でユーザーを必要としない暗黙的な手順に簡略化可能）を経てリダイレクトされ、その後アプリのリストが表示されます。

2. 現在ログインしているユーザーの詳細を表示する（OpenIDプロバイダーから取得した属性の集合）

   root@kitploit:~

    GET /app
   

UAAへの貢献

コミュニティに参加する方法はいくつかあります：

• メーリングリストでCloud Foundryコミュニティに参加してください。メーリングリストで質問に答えたり議論に参加してご協力ください。
• githubでバグや新機能のチケットを作成し、興味のあるものにコメントや投票をしてください。
• Githubはソーシャルコーディングの場です：コードを書きたい場合は、このリポジトリのフォークからのプルリクエストによる貢献を推奨します。この方法でコードを貢献する場合は、対応する特定の問題をカバーする既存のIssueがあれば参照してください。常に"develop"ブランチにプルリクエストを送信してください。
• cloudfoundry.orgブログを購読して、Cloud Foundryに関する今後の記事をチェックしてください。

謝辞

• YourKitはフル機能のJava Profilerでオープンソースプロジェクトをサポートしています。YourKit, LLCはYourKit Java ProfilerおよびYourKit .NET Profilerの開発元であり、Javaおよび.NETアプリケーションのプロファイリングのための革新的でインテリジェントなツールです。