adal 1.0.0

data/samples/client_assertion_certificate_example/README.md

@@ -0,0 +1,42 @@
+## Authenticating with a Certificate and Private Key
+
+### Set-Up
+1. Register a web application in the Azure portal. Note it's client id.
+2. Generate a self-issued certificate with key length >= 2048. Using the Windows makecert.exe utility, this can be done with:
+
+   ```
+   makecert -r -pe -n "CN=Name of Certificate" -b 07/01/2015 -e 07/01/2017 -ss my -len 2048
+   ```
+3. Export the certificate from Certificate Manager to a file.
+4. Get the base 64 thumbprint, base 64 value and key id from the certificate. With Windows powershell, this can be done with:
+
+   ```
+   $cer = New-Object System.Security.Cryptograph.X509Certificates.X509Certificate2
+   $cer.Import(".\path\to\cert\from\step3.cer")
+   $base64thumbprint = [System.Convert]::ToBase64String($cer.GetRawCertData())
+   $base64value = [System.Convert]::ToBase64String($cer.GetRawCertData())
+   $keyId = [System.Guid]::NewGuid().ToString()
+   ```
+5. Download the manifest for the registered web application, add the following entry to the keyCredentials array and reupload it:
+
+   ```
+   {
+     "customKeyIdentifier": "[base 64 thumbprint]",
+     "keyId": "[key id]",
+     "type": "AsymmetricX509Cert",
+     "usage": "Verify",
+     "value": "[base 64 value]"
+   }
+   ```
+6. Export the certificate as a PFX (PKCS12). This can be done via the Windows Certificate Manager GUI.
+7. Fill in your tenant, client id of the web application and path and password to your .pfx file in app.rb.
+
+### Run
+Run the app as ```ruby app.rb```.
+
+## Common problems
+### I get an error that looks like: 
+```
+...net/http.rb:xxx: in connect SSL_connect returned=1 errno=0 state=SSLv3 read server certificate verify failed (OpenSSL::SSL::SSLError)
+```
+This is likely because you are on a Windows system and installed a Ruby installation that ships OpenSSL with no certificate authorities. The most common offender is RailsInstaller. [Solution](https://gist.github.com/fnichol/867550).

data/samples/client_assertion_certificate_example/app.rb

@@ -0,0 +1,55 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2015 Micorosft Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#-------------------------------------------------------------------------------
+
+# See the accompanying README.md for instructions on how to set-up an
+# application to run this sample.
+
+require 'adal'
+require 'openssl'
+
+# This will make ADAL log the various steps of JWT creation from certificates.
+ADAL::Logging.log_level = ADAL::Logger::VERBOSE
+
+AUTHORITY_HOST = ADAL::Authority::WORLD_WIDE_AUTHORITY
+CLIENT_ID = 'your client id here'
+RESOURCE = 'https://outlook.office365.com'
+TENANT = 'your tenant here.onmicrosoft.com'
+
+PFX_PATH = './path/to/your/cert.pfx'
+PFX_PASSWORD = 'password'
+
+pfx = OpenSSL::PKCS12.new(File.read(PFX_PATH), PFX_PASSWORD)
+
+authority = ADAL::Authority.new(AUTHORITY_HOST, TENANT)
+client_cred = ADAL::ClientAssertionCertificate.new(authority, CLIENT_ID, pfx)
+result = ADAL::AuthenticationContext
+         .new(AUTHORITY_HOST, TENANT)
+         .acquire_token_for_client(RESOURCE, client_cred)
+
+case result
+when ADAL::SuccessResponse
+  puts 'Successfully authenticated with client credentials. Received access ' \
+       "token: #{result.access_token}."
+when ADAL::FailureResponse
+  puts 'Failed to authenticate with client credentials. Received error: ' \
+       "#{result.error} and error description: #{result.error_description}."
+end

data/samples/on_behalf_of_example/README.md

@@ -0,0 +1,35 @@
+# Authenticating On Behalf of a User
+
+This sample consists of two applications that each use ADAL.
+
+The native application uses a username and password flow to obtain an access
+token and then uses that access token to access a resource: the web api.
+
+The web api takes the access token and exchanges it for an access token for
+the graph.windows.net resource and uses it to retrieve graph data, which it
+then sends back to the native app.
+
+Before running these applications, follow the instructions below to configure
+them to your tenant.
+
+
+## Configuring the Native Application
+1. In the Azure portal, register a new Web Application. Take note of the client
+   id and client secret. The application identifier can be anything, but take
+   note of what you choose for a future step.
+2. Give this application permission to use the web application that you create
+   in the next step. (You can't do this step until you've configured the Web
+   Application.)
+3. In `web_app.rb`, fill in the tenant, client id and client secret fields.
+
+## Configuring the Web Application
+1. In the Azure portal, register a new Native Application. Take note of the
+   client id.
+2. Give this application permission to `Read directory data.`.
+3. In `native_app.rb`, fill in the tenant and client id field. Fiell in the
+   `WEB_API_RESOURCE` field with the application identifier that you used
+   previously.
+
+## Running the application
+1. Start the web application with `ruby web_api.rb`.
+2. Run the native application with `ruby native_app.rb`.

data/samples/on_behalf_of_example/native_app.rb

@@ -0,0 +1,52 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2015 Micorosft Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#-------------------------------------------------------------------------------
+
+require 'adal'
+require 'json'
+
+def prompt(*args)
+  print(*args)
+  gets.strip
+end
+
+# Uncomment this if you want to trace ADAL's execution.
+# ADAL::Logging.log_level = ADAL::Logger::VERBOSE
+
+AUTHORITY_HOST = ADAL::Authority::WORLD_WIDE_AUTHORITY
+TENANT = 'your tenant here.onmicrosoft.com'
+CLIENT_ID = 'your client id here'
+WEB_API_RESOURCE = 'https://your tenant here.onmicrosoft.com/MyWebService'
+WEB_API_ENDPOINT = 'http://localhost:44321/api/graph'
+
+user_cred = ADAL::UserCredential.new(prompt('Username: '), prompt('Password: '))
+ctx = ADAL::AuthenticationContext.new(AUTHORITY_HOST, TENANT)
+
+token_response =
+  ctx.acquire_token_for_user(WEB_API_RESOURCE, CLIENT_ID, user_cred)
+
+web_api_uri = URI(WEB_API_ENDPOINT)
+headers = { 'Bearer' => token_response.access_token }
+http = Net::HTTP.new(web_api_uri.hostname, web_api_uri.port)
+web_api_response = http.get(web_api_uri, headers)
+
+puts 'Here is your directory user graph:'
+puts JSON.pretty_generate(JSON.parse(web_api_response.body))

data/samples/on_behalf_of_example/web_api.rb

@@ -0,0 +1,71 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2015 Micorosft Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#-------------------------------------------------------------------------------
+
+require_relative '../../lib/adal'
+require 'sinatra'
+
+# Uncomment this if you want to trace ADAL's execution.
+# ADAL::Logging.log_level = ADAL::Logger::VERBOSE
+
+AUTHORITY_HOST = ADAL::Authority::WORLD_WIDE_AUTHORITY
+TENANT = 'your tenant here.onmicrosoft.com'
+RESOURCE = 'https://graph.windows.net'
+CLIENT_ID = 'your client id here'
+CLIENT_SECRET = 'your client secret here'
+
+set :client_cred, ADAL::ClientCredential.new(CLIENT_ID, CLIENT_SECRET)
+set :ctx, ADAL::AuthenticationContext.new(AUTHORITY_HOST, TENANT)
+set :port, 44_321
+
+before do
+  # If the client does not send an access token, then he is unauthorized.
+  halt 401 unless env['HTTP_BEARER']
+
+  token = exchange_tokens(env['HTTP_BEARER'])
+  env[:access_token] = token.access_token
+
+  # If we cannot exchange the clients access token for a new one, then he is
+  # unauthorized.
+  halt 401 unless env[:access_token]
+end
+
+# Fetches the contents of the /users graph endpoint.
+get '/api/graph' do
+  graph_uri = URI(RESOURCE + '/' + TENANT + '/users?api-version=2013-04-05')
+  headers = { 'authorization' => env[:access_token] }
+  http = Net::HTTP.new(graph_uri.hostname, graph_uri.port)
+  http.use_ssl = true
+  http.get(graph_uri, headers).body
+end
+
+##
+# Exchanges an access token for this web api for an access token for another
+# resource.
+#
+# @param String access_token
+#   The token for this web service, from the client.
+# @return String
+#   An access token for the designated resource.
+def exchange_tokens(access_token)
+  settings.ctx.acquire_token_for_user(
+    RESOURCE, settings.client_cred, ADAL::UserAssertion.new(access_token))
+end

data/samples/user_credentials_example/README.md

@@ -0,0 +1,7 @@
+This simple application demonstrates how to use ADAL to acquire access tokens
+with the username/password flow.
+
+To run the application:
+
+1. Replace the `CLIENT_ID` and `TENANT` fields with your client id and tenant.
+2. Run `ruby app.rb`.

data/samples/user_credentials_example/app.rb

@@ -0,0 +1,52 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2015 Micorosft Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#-------------------------------------------------------------------------------
+
+require 'adal'
+
+# This will make ADAL log the various steps of obtaining an access token.
+ADAL::Logging.log_level = ADAL::Logger::VERBOSE
+
+AUTHORITY_HOST = ADAL::Authority::WORLD_WIDE_AUTHORITY
+CLIENT_ID = 'your clientid here'
+RESOURCE = 'https://graph.windows.net'
+TENANT = 'your tenant here.onmicrosoft.com'
+
+def prompt(*args)
+  print(*args)
+  gets.strip
+end
+
+username = prompt 'Username: '
+password = prompt 'Password: '
+
+user_cred = ADAL::UserCredential.new(username, password)
+ctx = ADAL::AuthenticationContext.new(AUTHORITY_HOST, TENANT)
+result = ctx.acquire_token_for_user(RESOURCE, CLIENT_ID, user_cred)
+
+case result
+when ADAL::SuccessResponse
+  puts 'Successfully authenticated with user credentials. Received access ' \
+       "token: #{result.access_token}."
+when ADAL::FailureResponse
+  puts 'Failed to authenticate with client credentials. Received error: ' \
+       "#{result.error} and error description: #{result.error_description}."
+end

data/spec/adal/authentication_context_spec.rb

@@ -0,0 +1,186 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2015 Micorosft Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#-------------------------------------------------------------------------------
+
+require_relative '../support/fake_data'
+
+require 'spec_helper'
+
+# Load constants used by the fake token endpoint.
+include FakeData
+
+describe ADAL::AuthenticationContext do
+  let(:auth_ctx) { ADAL::AuthenticationContext.new(AUTHORITY, TENANT) }
+  let(:client_cred) { ADAL::ClientCredential.new(CLIENT_ID, CLIENT_SECRET) }
+
+  describe '#authorization_request_url' do
+    let(:resource) { 'http://graph.windows.net' }
+    let(:client_id) { 'some-client-id' }
+    let(:redirect_uri) { 'http://contoso.com/login' }
+
+    context 'with no extra params' do
+      it 'should produce the correct request url' do
+        authorization_url =
+          auth_ctx.authorization_request_url(resource, client_id, redirect_uri)
+        expect(authorization_url.to_s.strip)
+          .to eq "https://#{AUTHORITY}/#{TENANT}/oauth2/authorize?client_id=" \
+                 "#{client_id}&response_mode=form_post&redirect_uri=http%3A%2" \
+                 'F%2Fcontoso.com%2Flogin&resource=http%3A%2F%2Fgraph.windows' \
+                 '.net&response_type=code'
+      end
+    end
+
+    context 'with extra params' do
+      it 'should produce the correct request url' do
+        params = { foo: :bar }
+        authorization_url = auth_ctx.authorization_request_url(
+          resource, client_id, redirect_uri, params)
+        expect(authorization_url.to_s.strip)
+          .to eq "https://#{AUTHORITY}/#{TENANT}/oauth2/authorize?client_id=" \
+                 "#{client_id}&response_mode=form_post&redirect_uri=http%3A%2" \
+                 'F%2Fcontoso.com%2Flogin&resource=http%3A%2F%2Fgraph.windows' \
+                 '.net&response_type=code&foo=bar'
+      end
+    end
+  end
+
+  describe '#correlation_id=' do
+    let(:correlation_id) { 'correlation_id_1' }
+    let(:user) { ADAL::UserAssertion.new(USER_ASSERTION) }
+
+    it 'should put the correlation id on all request headers' do
+      auth_ctx.correlation_id = correlation_id
+      stub_request(:post, %r{.*#{TENANT}\/oauth2\/token})
+        .with(headers: { 'client-request-id' => correlation_id })
+        .and_return(body: '{"access_token":"my access token"}')
+      result = auth_ctx.acquire_token_for_user(RESOURCE, CLIENT_ID, user)
+      expect(result.access_token).to eq('my access token')
+    end
+  end
+
+  describe '#acquire_token_with_authorization_code' do
+    it 'should return a SuccessResponse when successful' do
+      token_response = auth_ctx.acquire_token_with_authorization_code(
+        AUTH_CODE, REDIRECT_URI, client_cred, RESOURCE)
+      expect(token_response).to be_a(ADAL::SuccessResponse)
+    end
+
+    it 'should return an ErrorResponse when unauthorized' do
+      token_response = auth_ctx.acquire_token_with_authorization_code(
+        AUTH_CODE, 'bad', client_cred, RESOURCE)
+      expect(token_response).to be_a(ADAL::ErrorResponse)
+    end
+
+    it 'should fail if any of the required parameters are nil' do
+      expect do
+        auth_ctx.acquire_token_with_authorization_code(
+          nil, REDIRECT_URI, client_cred, RESOURCE)
+      end.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#acquire_token_for_client' do
+    it 'should return a SuccessResponse when successful' do
+      response = auth_ctx.acquire_token_for_client(RESOURCE, client_cred)
+      expect(response).to be_a(ADAL::SuccessResponse)
+    end
+
+    it 'should return an ErrorResponse when unauthorized' do
+      token_response = auth_ctx.acquire_token_for_client(RESOURCE, 'bad')
+      expect(token_response).to be_a(ADAL::ErrorResponse)
+    end
+
+    it 'should fail if any of the parameters are nil' do
+      expect do
+        auth_ctx.acquire_token_for_client(RESOURCE, nil)
+      end.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#acquire_token_with_refresh_token' do
+    it 'should return a SuccessResponse when successful' do
+      token_response = auth_ctx.acquire_token_with_refresh_token(
+        REFRESH_TOKEN, client_cred, RESOURCE)
+      expect(token_response).to be_a(ADAL::SuccessResponse)
+    end
+
+    it 'should return an ErrorResponse when unauthorized' do
+      token_response = auth_ctx.acquire_token_with_refresh_token(
+        REFRESH_TOKEN, 'bad', RESOURCE)
+      expect(token_response).to be_a(ADAL::ErrorResponse)
+    end
+
+    it 'should return an ErrorResponse when the refresh token is invalid' do
+      token_response = auth_ctx.acquire_token_with_refresh_token(
+        'bad', client_cred, RESOURCE)
+      expect(token_response).to be_a(ADAL::ErrorResponse)
+    end
+
+    it 'should fail if any of the required parameters are nil' do
+      expect do
+        auth_ctx.acquire_token_with_refresh_token(
+          nil, client_cred, RESOURCE)
+      end.to raise_error(ArgumentError)
+    end
+  end
+
+  describe '#acquire_token_for_user' do
+    context 'with valid parameters' do
+      let(:user) { ADAL::UserAssertion.new(USER_ASSERTION) }
+      subject { auth_ctx.acquire_token_for_user(RESOURCE, client_cred, user) }
+
+      it { is_expected.to be_a(ADAL::SuccessResponse) }
+    end
+
+    context 'with invalid parameters' do
+      it 'should fail' do
+        expect { auth_ctx.acquire_token_for_user(nil, nil) }
+          .to raise_error(ArgumentError)
+      end
+    end
+
+    context 'with a UserIdentifier' do
+      let(:user) { ADAL::UserIdentifier.new(USERNAME, :DISPLAYABLE_ID) }
+      context 'with a matching token in the cache' do
+        subject { auth_ctx.acquire_token_for_user(RESOURCE, client_cred, user) }
+        before(:each) do
+          @first_response = auth_ctx.acquire_token_with_authorization_code(
+            AUTH_CODE, REDIRECT_URI, client_cred, RESOURCE)
+        end
+
+        it { is_expected.to_not be nil }
+
+        it 'should return the token from the cache' do
+          expect(subject).to eq @first_response
+        end
+      end
+
+      context 'with no matching token in the cache' do
+        subject do
+          -> { auth_ctx.acquire_token_for_user(RESOURCE, client_cred, user) }
+        end
+        it do
+          is_expected.to raise_error ADAL::TokenRequest::UserCredentialError
+        end
+      end
+    end
+  end
+end