power-bi 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5aaadec6cec57b22f4780dd2e1f4c64c55872d49f5a17a59326fcff099844dd
-  data.tar.gz: 1a6bf8c48a1d17333f58519c5ee23ee9a85025c63110c6cc2f2fe9243566f7ca
+  metadata.gz: c120eeef2ac35b02afcfff32690f003efad7fbfd59c7f2bd714a6d0659b1ed44
+  data.tar.gz: ee077e4fa8f6faae52ad5c1107fd96f9cb8bae5e7c8f0ef47a83009e7c80ce0d
 SHA512:
-  metadata.gz: 570af0ad49001778d237e4ce712a8120d879cc83d53a9b4a877d2d51ee6fcc3dde4e913cc8a3c42273ce5de45d31d7922308fee03c895fb6fcbce46332b06288
-  data.tar.gz: 760813b41e3318fc52871f3adc61f4efcf518f9333f93fcf9295c15b9e61d094518cbd3adbbf7fec0c3c7921239d2082460099fc2adffcd4b60c15067e5946e1
+  metadata.gz: c9c742362808fb3fa08ad663ebbdaf34d916f932fa5bed8f66d657caf769c230a7694d82cd05555a642d41098ccb9fcf6eed9b6f89233ca344ff3f1c3d02b6fb
+  data.tar.gz: dc28a5e89d26365b7b48d5f6538bd1e8c12a9fe45c81b4f216ae63074ced3b728f31395c98751ee571a9e7234315693af5f6a7cffe4d86c398f6ec6683cfeafe

data/README.md

@@ -10,6 +10,60 @@ The Power BI API does not handle the authorization part. It requires the user to
 pbi = PowerBI::Tenant.new(->{token = get_token(client, token) ; token.token})
 ```
 
+## Authentication & authorization towards the Power BI API
+
+Currently (april 2024), there are basically 3 ways to authenticate to the Power BI API.
+
+### 1 - Master User
+
+A master user is a classic Microsoft 365 user that you assign a Power BI Pro license.  In order to allow the user to execute actions on the Power BI API you need to create an app registration in Azure AD.  In the associated Enterprise application (gets created when you create the app registration), you need to add the permissions to use the Power BI service.
+
+The resulting authentication looks like this:
+
+```
+TENANT = "53c835d6-6841-4d58-948a-55117409e1d8"
+CLIENT_ID = '6fc64675-bee3-49a7-70d8-b3301a51a88d'
+CLIENT_SECRET = 'sI/@ncYe=eVt7.XfZ7tsPU1aPbxm0V_H'
+USERNAME = 'company_0001@example.com'
+PASSWORD = 'mLXv5A1jrIb8dHopur7y'
+
+client = OAuth2::Client.new(CLIENT_ID, CLIENT_SECRET, site: 'https://login.microsoftonline.com', token_url: "#{TENANT}/oauth2/token")
+
+token = client.password.get_token(USERNAME, PASSWORD, scope: 'openid', resource: 'https://analysis.windows.net/powerbi/api')
+```
+
+Note that in this case the legacy (and slightly unsafe) Resource Owner Password Credentials (ROPC) OAuth flow is used.
+
+### 2 - Service principal
+
+A service principal is a fancy word for a machine user with a secret (eg. id + key) in Azure AD.  You create them by creating an app registration and adding a secret on it.  You need to allow service principals in your Power BI admin settings. But once you allow that, the setup is very easy.  No need to configure anything special in AD.
+
+The resulting authentication looks like this:
+
+```
+TENANT = "53c835d6-6841-4d58-948a-55117409e1d8"
+CLIENT_ID = '6fc64675-bee3-49a7-70d8-b3301a51a88d'
+CLIENT_SECRET = 'sI/@ncYe=eVt7.XfZ7tsPU1aPbxm0V_H'
+
+client = OAuth2::Client.new(CLIENT_ID, CLIENT_SECRET, site: 'https://login.microsoftonline.com', token_url: "#{TENANT}/oauth2/token")
+
+token = client.client_credentials.get_token(resource: 'https://analysis.windows.net/powerbi/api')
+```
+
+Note that in this case the Client Credentials OAuth flow is used.
+
+### 3 - Service principal profiles
+
+Service principal profiles is a Power-BI-only concept.  Towards AD, it looks exactly the same as generic service principal.  Hence the authenication looks exactly as in way 2.
+
+Once authenticated, you can set profiles like this:
+
+```
+pbi.profile = profile
+```
+
+Every action executed after setting the profile, will be executed _through the eyes of the profile_.  This way, you can create an isolated multi-tenant setup.  Using profiles, simplifies the internal organization of Power BI and allows faster interaction with Power BI.  This also lifts the 1000-workspaces limit that is imposed on Master Userss and Service Principals
+
 # Supported endpoints
 
 Note: where possible we use _lazy evaluation_: we only call the REST API endpoint when really needed. For examples `pbi.workspaces` won't trigger a call, while `pbi.workspaces.count` will trigger a call.  And `pbi.workspace('123')` won't trigger a call, while `pbi.workspace('123').name` will trigger a call.
@@ -75,6 +129,13 @@ Note: Capacities are Azure creatures, you can't create them in Power BI.
 * List capacities: `pbi.capacities`
 * Get a capacity: `pbi.capacity(id)`
 
+## Profiles
+
+* List profiles: `pbi.profiles`
+* Get a profile: `pbi.profile(id)`
+* Create a profile: `pbi.profiles.create`
+* Delete a profile: `profile.delete`
+
 # Note about gateway credentials
 
 Power BI uses an obscure mechanism to encrypt credential exchange between the service and the gateway.  The encryption must be done outside this module on a Windows machine based on th public key of the gateway.  This is an example C# script:

data/lib/power-bi/profile.rb

@@ -0,0 +1,44 @@
+module PowerBI
+  class Profile < Object
+
+    def initialize(tenant, parent, id = nil)
+      super(tenant, id)
+    end
+
+    def get_data(id)
+      @tenant.get("/profiles/#{id}")
+    end
+
+    def data_to_attributes(data)
+      {
+        id: data[:id],
+        display_name: data[:displayName],
+      }
+    end
+
+    def delete
+      @tenant.delete("/profiles/#{@id}")
+      @tenant.profiles.reload
+      true
+    end
+
+  end
+
+  class ProfileArray < Array
+    def self.get_class
+      Profile
+    end
+
+    def create(name)
+      data = @tenant.post("/profiles") do |req|
+        req.body = {displayName: name}.to_json
+      end
+      self.reload
+      Profile.instantiate_from_data(@tenant, nil, data)
+    end
+
+    def get_data
+      @tenant.get("/profiles")[:value]
+    end
+  end
+end

data/lib/power-bi/tenant.rb

@@ -1,13 +1,15 @@
 module PowerBI
   class Tenant
-    attr_reader :workspaces, :gateways, :capacities
+    attr_reader :workspaces, :gateways, :capacities, :profiles, :profile
 
     def initialize(token_generator, retries: 5, logger: nil)
       @token_generator = token_generator
       @workspaces = WorkspaceArray.new(self)
       @gateways = GatewayArray.new(self)
       @capacities = CapacityArray.new(self)
+      @profiles = ProfileArray.new(self)
       @logger = logger
+      @profile = nil
 
       ## WHY RETRIES? ##
       # It is noticed that once in a while (~0.1% API calls), the Power BI server returns a 500 (internal server error) without apparent reason, just retrying works :-)
@@ -42,6 +44,11 @@ module PowerBI
       Capacity.new(self, nil, id)
     end
 
+    def profile=(profile)
+      @profile = profile
+      @workspaces.reload # we need to reload the workspaces because we look through the eyes of the profile
+    end
+
     def get(url, params = {})
       t0 = Time.now
       conn = Faraday.new do |f|
@@ -51,6 +58,9 @@ module PowerBI
         req.params = params
         req.headers['Accept'] = 'application/json'
         req.headers['authorization'] = "Bearer #{token}"
+        if @profile
+          req.headers['X-PowerBI-Profile-Id'] = @profile.id
+        end
         yield req if block_given?
       end
       if response.status == 400
@@ -73,6 +83,9 @@ module PowerBI
       response = conn.get(PowerBI::BASE_URL + url) do |req|
         req.params = params
         req.headers['authorization'] = "Bearer #{token}"
+        if @profile
+          req.headers['X-PowerBI-Profile-Id'] = @profile.id
+        end
         yield req if block_given?
       end
       log "Calling (GET - raw) #{response.env.url.to_s} - took #{((Time.now - t0) * 1000).to_i} ms"
@@ -92,6 +105,9 @@ module PowerBI
         req.headers['Accept'] = 'application/json'
         req.headers['Content-Type'] = 'application/json'
         req.headers['authorization'] = "Bearer #{token}"
+        if @profile
+          req.headers['X-PowerBI-Profile-Id'] = @profile.id
+        end
         yield req if block_given?
       end
       log "Calling (POST) #{response.env.url.to_s} - took #{((Time.now - t0) * 1000).to_i} ms"
@@ -113,6 +129,9 @@ module PowerBI
         req.headers['Accept'] = 'application/json'
         req.headers['Content-Type'] = 'application/json'
         req.headers['authorization'] = "Bearer #{token}"
+        if @profile
+          req.headers['X-PowerBI-Profile-Id'] = @profile.id
+        end
         yield req if block_given?
       end
       log "Calling (PATCH) #{response.env.url.to_s} - took #{((Time.now - t0) * 1000).to_i} ms"
@@ -133,6 +152,9 @@ module PowerBI
         req.params = params
         req.headers['Accept'] = 'application/json'
         req.headers['authorization'] = "Bearer #{token}"
+        if @profile
+          req.headers['X-PowerBI-Profile-Id'] = @profile.id
+        end
         yield req if block_given?
       end
       log "Calling (DELETE) #{response.env.url.to_s} - took #{((Time.now - t0) * 1000).to_i} ms"
@@ -158,6 +180,9 @@ module PowerBI
         req.headers['Accept'] = 'application/json'
         req.headers['Content-Type'] = 'multipart/form-data'
         req.headers['authorization'] = "Bearer #{token}"
+        if @profile
+          req.headers['X-PowerBI-Profile-Id'] = @profile.id
+        end
         req.body = {value: Faraday::UploadIO.new(file, 'application/octet-stream')}
         req.options.timeout = 120  # default is 60 seconds Net::ReadTimeout
       end

data/lib/power-bi.rb

@@ -24,4 +24,5 @@ require_relative "power-bi/gateway"
 require_relative "power-bi/gateway_datasource"
 require_relative "power-bi/page"
 require_relative "power-bi/user"
-require_relative "power-bi/capacity"
+require_relative "power-bi/capacity"
+require_relative "power-bi/profile"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: power-bi
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Lode Cools
@@ -98,6 +98,7 @@ files:
 - lib/power-bi/object.rb
 - lib/power-bi/page.rb
 - lib/power-bi/parameter.rb
+- lib/power-bi/profile.rb
 - lib/power-bi/refresh.rb
 - lib/power-bi/report.rb
 - lib/power-bi/tenant.rb