Este documento é confidencial e propriedade da Portugal Telecom. É estritamente proibido o uso não autorizado de informação nele incluído.

Service Delivery Broker

f o r AP I Managemen t Versão 0.3 – 2016-02-06

Service Delivery Broker for API Management 2

Indice

1. Termos Legais ........................................................................................................... 3

2. Introdução ................................................................................................................ 4

3. Gestão de Identidade e Controlo de Acessos .............................................................. 6

4. API Gateway ............................................................................................................. 9

5. SDB Backoffice .........................................................................................................10

6. API Portal & Marketplace .........................................................................................11

7. Microsoft Azure API Management ............................................................................12

Domínio Funcional ............................................................................................................ 12

Qualidade de Serviço ........................................................................................................ 13

Fornecedor ........................................................................................................................ 14

Pessoas e Equipas ............................................................................................................. 14

8. Histórico de Versões ................................................................................................15

Service Delivery Broker for API Management 3

1. Termos Legais

A INFORMAÇÃO CONTIDA NESTE DOCUMENTO É CONFIDENCIAL. NÃO É PERMITIDO, DIRETA OU

INDIRETAMENTE, USAR, VENDER, COPIAR, REPRODUZIR, DIVULGAR OU PUBLICAR QUALQUER

INFORMAÇÃO CONTIDA NESTE DOCUMENTO SEM UMA AUTORIZAÇÃO PRÉVIA E POR ESCRITO DA

PORTUGAL TELECOM.

EM NENHUMA CIRCUNSTÂNCIA A PORTUGAL TELECOM SERÁ RESPONSÁVEL POR DANOS DIRECTOS OU

INDIRETOS RESULTANTES DA UTILIZAÇÃO DESTE DOCUMENTO.

Service Delivery Broker for API Management 4

2. Introdução

A revolução digital introduz um impacto profundo em todas as organizações, que necessitam de se

transformar em “empresas digitais”, por forma a permanecerem competitivas na nova economia.

A emergência do desenvolvimento, disponibilização e suporte a aplicações baseadas em serviços digitais

colocou em evidência a necessidade de estandardização e exposição dos recursos através de APIs1, para

consumo interno e externo, geridos por forma a rentabilizarem eficientemente o investimento realizado

nos sistemas de informação, designadamente através de:

Reutilização funcional dos componentes de serviços e das aplicações legadas;

Autenticação de utilizadores, controle de acessos e serviços de federação de identidades;

Integração, adaptação e orquestração de serviços;

Abstração da complexidade dos recursos de TI.

Por forma a satisfazer essas necessidades, posiciona-se o Service Delivery Broker2 (SDB), um produto

criado, desenvolvido e extensivamente utilizado pela Portugal Telecom para gerir o ecossistema de

aplicações e serviços multiplataforma (Web, mobile e IPTV) da MEO3, baseando-se na Service Delivery

Framework4 do TM Forum5, nos princípios e padrões da Orientação a Serviços (SOA6) e em boas práticas

de ITSM7.

Domínios da função de API Management no SDB

1 https://en.wikipedia.org/wiki/Application_programming_interface 2 http://sdb.sapo.pt/en/index.html 3 https://www.meo.pt/ 4 https://en.wikipedia.org/wiki/Service_delivery_framework 5 https://www.tmforum.org/ 6 https://en.wikipedia.org/wiki/Service-oriented_architecture 7 https://en.wikipedia.org/wiki/IT_service_management

Service Delivery Broker for API Management 5

Especificamente projetado para mediar e gerir interações entre qualquer dispositivo habilitado para a

Web e serviços heterogéneos, o SDB oferece capacidades integradas de gestão e monitorização em tempo

real e a possibilidade de interação com qualquer aplicação ou serviço compatível com SOA.

Quando analisado em comparação 8 com outros produtos, o SDB apresenta diversos aspetos

diferenciadores:

• Suporta nativamente não apenas os Web standards “clássicos” (e.g. SOAP, XML, WS-Security),

mas também os mais recentes (REST, JSON, OAuth 2.09, OpenId Connect10, JWT11), integrando os

processos existentes, ampliando e evoluindo os sistemas e as aplicações de modo incremental e

não-intrusivo, ajustando-se aos requisitos do negócio;

• Garante que o governo de TI e as boas práticas de ITSM são validadas e seguidas através do ciclo

de vida dos serviços, automatizando os aspetos mais críticos durante as fases de Desenho,

Desenvolvimento, Transição e Operação;

• Oferece a utilizadores internos e externos uma experiência natural e fácil de seguir em cada fase

do ciclo de vida dos serviços, reduzindo bastante o trabalho necessário para criar, configurar,

testar, publicar, consumir e monitorizar serviços bem desenhados para operarem em ambientes

multiplataforma e multicanal.

Finalista dos prémios “Business Innovation Excellence Award” do TM Forum e do “Open Innovation

Award”, atribuído pela Pipeline Magazine, o SDB é positivamente referenciado por diversas entidades12.

As seções seguintes descrevem as componentes principais do SDB e a forma como se interrelacionam para

alavancarem o suporte aos objetivos de negócio prosseguidos pelos projetos de TI em qualquer tipo de

organização.

8 V. seção “Microsoft Azure API Management” neste documento. 9 http://oauth.net/2/. 10 http://openid.net/connect/. 11 http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-11. 12 http://sdb.sapo.pt/pt/quotes.html.

Service Delivery Broker for API Management 6

3. Gestão de Identidade e Controlo de Acessos

A forma como as aplicações lidam com a autenticação dos utilizadores e realizam a autorização de acesso

aos recursos é crítica para garantir a segurança e confidencialidade da informação.

A autenticação de utilizadores e obtenção de autorizações de acesso a serviços (APIs) da componente de

Identity & Access Management do SDB fundamentou-se nos seguintes princípios:

• A aplicação NÃO DEVE requerer ao utilizador que insira as suas credenciais diretamente na

aplicação.

Após clicarem em “Login”, a aplicação DEVE redirecionar os utilizadores para o fornecedor de identidade, para que os utilizadores apenas insiram as credenciais na página de login do fornecedor de identidade.

• A aplicação DEVE poder integrar com qualquer fornecedor de identidade, e de alterar

dinamicamente os fornecedores de identidade utilizados, sem necessidade de requerer novos

desenvolvimentos.

Em vez de integrar diretamente com um ou vários fornecedores de identidade, a aplicação DEVE usar uma Gateway de Identidade, que mediará todas as interações entre a aplicação e os seus fornecedores de identidade, por forma a efetivamente abstrair da aplicação os detalhes de integração particulares de cada fornecedor de identidade.

• A aplicação DEVE depender apenas de atributos de identidade standard.

Os atributos de identidade providenciados pelo fornecedor de identidade DEVEM ser padronizados, de acordo com o protocolo utilizado, e os atributos que sejam específicos de um determinado fornecedor de identidade devem ser claramente identificados, para que a aplicação possa decidir quando e como pretende utilizar esses atributos.

• A aplicação DEVE ser capaz de requisitar e usar tokens de acesso a serviços em nome dos seus

utilizadores.

A aplicação DEVE ser capaz de requisitar tokens válidos para aceder aos serviços, apresentando o código de autorização que recebeu após a autenticação do utilizador com sucesso, assim evitando a necessidade de gerir um conjunto distinto de tokens de acesso a serviços que teriam de ser obtidos fora de banda do processo de autenticação.

• DEVE existir e ser disponibilizada uma experiência integrada para os diferentes perfis:

utilizadores, programadores e administradores de aplicações Web, mobile e TV.

A aplicação DEVE ser integrada numa infraestrutura que suporta os diferentes perfis que necessitam de interagir com a configuração da aplicação: os programadores que criam novas aplicações, os utilizadores que concedem às aplicações permissões de acesso a serviços, e os administradores que criam e editam os escopos de aplicações.

• DEVE ser fornecido um conjunto de princípios que apresentam e descrevem um processo

simples e suportado em standards para a integração de novas aplicações.

Por forma a reduzir o tempo e esforço de desenvolvimento, DEVE ser disponibilizado um conjunto de princípios de integração que expliquem claramente os objetivos a serem alcançados, os princípios por detrás dos objetivos, e incluam exemplos dos protocolos utilizados na integração.

Service Delivery Broker for API Management 7

O seguinte diagrama representa as componentes principais do SDB para suportar o modelo de segurança

preconizado, cuja implementação se baseia nos princípios apresentados anteriormente.

Modelo de segurança do SDB para aplicações e serviços digitais

De acordo com a arquitetura proposta, a aplicação, em vez de solicitar ao utilizador que insira as suas

credenciais diretamente na aplicação, apenas mostra um botão de “Login” que, quando clicado,

redireciona o utilizador para o SDB Identity Gateway.

Por sua vez, o SDB Identity Gateway redireciona o utilizador para a página de login do fornecedor de

identidade configurado para responder aos pedidos de autenticação da aplicação, por exemplo, o

Fornecedor de Identidade corporativa da organização, ou um qualquer fornecedor de identidade social

(e.g. Google, Facebook, Twitter, LinkedIn, SAPO, etc.). Já na página de login do fornecedor de identidade,

o utilizador insere as suas credenciais, por forma a autenticar-se.

Depois de autenticado com sucesso, o utilizador é automaticamente redirecionado de volta à aplicação

que iniciou o fluxo. Nesta altura, a aplicação recebe um código que pode trocar por uma senha (token)

com uma validade temporal, que a autoriza a aceder a serviços (APIs) em nome do utilizador que se

autenticou, e/ou a obter informação adicional sobre o perfil desse utilizador.

No contexto da organização, o SDB introduz diversos benefícios que endereçam os problemas

relacionados com a segurança dos processos de autenticação utilizados, acrescendo o potencial deste

suporte ser reutilizado em todo o tipo de aplicações (e.g. Web e mobile):

• O protocolo utilizado entre as aplicações e o SDB Connect é OpenID Connect, uma evolução do

protocolo OAuth 2.0, com a adição de suporte explícito à autenticação e obtenção de informação

adicional sobre o utilizador13;

13 http://openid.net/specs/openid-connect-core-1_0.html#Overview.

Service Delivery Broker for API Management 8

• As aplicações não necessitam de conhecer as credenciais dos utilizadores, nem de aceder

diretamente a serviços de diretório (e.g. Active Directory), ou às bases de dados em que residem

as credenciais dos utilizadores;

• O SDB estandardiza a forma de integração e simplifica o esforço necessário, tornando mais seguro

tanto o acesso aos serviços, como a utilização dos atributos de identidade dos utilizadores.

Service Delivery Broker for API Management 9

4. API Gateway

O SDB API Gateway é um componente fundamental para a realização dos objetivos associados à camada

de serviços da organização, sendo responsável pelo suporte, controle e segurança de todas as mensagens,

designadamente suportando as necessidades de comunicação e abertura à exposição pública de APIs para

além do perímetro da rede interna da organização.

Service Control Gateway - Gartner, 2014

A mediação de pedidos a APIs, que decorre da utilização do SDB API Gateway, materializa diversas

vantagens para a gestão de recursos:

Motor de atendimento de pedidos a APIs de alto desempenho, escalável e com baixa latência,

capaz de mediar a comunicação entre os consumidores e os fornecedores de serviços;

Visibilidade e suporte à semântica dos protocolos Web, incluindo MIME types, HTTP Authorization

and Caching headers, etc.;

Diversos protocolos Web-based, incluindo transformações de formato e modelos de dados entre

todos os standards comummente usados na Web (WS-*, SOAP, XML, REST, JSON, etc.);

Roteamento baseado em conteúdo das mensagens, resiliência a falhas, balanceamento de carga,

e propagação de pedidos por vários destinos;

Validação de mecanismos e protocolos de autenticação, suportando as aplicações internas,

externas, programadores e utilizadores finais;

Service Delivery Broker for API Management 10

5. SDB Backoffice

A disponibilidade de um Catálogo Técnico que descreva todas as funcionalidades disponíveis nas APIs e

aplicações existentes é essencial para possibilitar a reutilização do investimento e a segurança do

ecossistema de serviços da organização.

Catalogando e relacionando explicitamente os meta-dados de registo e consumo de cada API, o SDB

Backoffice possibilita a configuração e a atribuição de conjuntos de permissões de acesso a APIs (scopes

de OAuth), implicitamente obtendo as relações entre as aplicações e as APIs usadas (autorizadas) em cada

aplicação, de acordo com “Principle of Least Privilege”14. As permissões concedidas no momento do

aprovisionamento da aplicação são depois verificadas pelo SDB em tempo de execução, nos termos

descritos anteriormente, na seção de Identidade e Gestão de Acessos.

Através deste suporte, o SDB reduz substancialmente o risco de acessos indesejáveis, dando maior

visibilidade e controlo centralizado sobre a segurança dos acessos a recursos críticos, bem como em

relação à disponibilidade e performance dos serviços e sistemas.

Para suportar os processos descritos na seção anterior, o SDB Backoffice implementa um sistema de

controlo de acessos baseado em perfis (Role-Based Access Control, ou RBAC15).

No caso particular da implementação do sistema RBAC no SDB Backoffice, é disponibilizada bastante

flexibilidade, pela possibilidade de criação de novos perfis e da configuração das respetivas permissões,

viabilizando-se desse modo o suporte à criação de um ecossistema assente na colaboração entre equipas,

com diferentes responsabilidades, que interagem sobre o ciclo de vida de um serviço: gestão, equipas de

desenvolvimento, parceiros de integração, equipas de suporte, fornecedores, etc.

Atividades de gestão do ciclo de vida dos serviços suportada no SDB Backoffice

Não obstante a flexibilidade disponível, é possível a consulta todas as alterações realizadas pelos

utilizadores e ter visibilidade sobre o estado do sistema, antes e depois de cada alteração. Os resultados

práticos que decorrem da existência deste ecossistema são: uma maior agilidade no desenvolvimento,

mais oportunidades de colaboração e comunicação entre as equipas, acrescidas de maior visibilidade

sobre a responsabilidade das alterações realizadas.

14 http://en.wikipedia.org/wiki/Principle_of_least_privilege. 15 http://en.wikipedia.org/wiki/Role-based_access_control.

Service Delivery Broker for API Management 11

6. API Portal & Marketplace

O SDB disponibiliza um Developers Portal que, para além da documentação relevante para os

programadores integrarem APIs da organização e de terceiros em aplicações, também disponibiliza a

funcionalidade de API Marketplace. Em conjunto, estes dois componentes são críticos para posicionarem

a comunicação e a alavancarem a promoção do portefólio de serviços da organização, posicionando os

seus serviços num ecossistema aberto e seguro, que permite a inovação por indivíduos e empresas.

Simulação do interface de utilizador do SDB Marketplace

A título de exemplo, depois de configurado, o SDB Marketplace permite a venda de acesso a um serviço

(APIs), segundo um modelo de negócio pré-pago (por exemplo, um pack de 500 notificações por SMS), ou

de subscrição temporal. Por exemplo, a subscrição de acesso a um serviço de conteúdos como Pontos de

Interesse (POI) georreferenciados, por um período de tempo determinado.

Em ambos os modelos, não são tipicamente necessárias alterações às APIs já existentes para viabilizar a

sua exposição no SDB Marketplace. O pagamento é realizado online, recorrendo a uma gateway de

pagamentos externa, e o SDB assegura a contabilização de todos os pedidos em tempo real, bem como o

registo e a comunicação das transações para efeitos de faturação.

Service Delivery Broker for API Management 12

7. Microsoft Azure API Management

A informação disponibilizada nesta seção destina-se a disponibilizar um conjunto de critérios relevantes16

para guiar a seleção de uma solução de API Management.

Ilustrando a utilização dos critérios para esse objetivo, foi realizada a análise da oferta de serviços de Azure

API Management17 da Microsoft, em comparação com a oferta de serviços de SDB da PT.

Domínio Funcional

Critério Descrição MS API Mng PT SDB

Gestão/Configuração Facilidade de desempenho de tarefas

administrativas de gestão e configuração de APIs

Sim Sim

Experiência do consumidor de

APIs

Portal para developers, facilidade de criação e

publicação de documentação, pesquisa, registo

em self-service e acesso a APIs.

Sim Sim

Limitação de tráfego Capacidade de limitar o número de pedidos a

APIs por cada cliente, restringindo o tráfego

enviado por cada cliente de acordo com o limite

pré-definido.

Sim Sim

Monetização Possibilidade de configurar e personalizar regras

de monetização para cada API.

Não18 Sim

Roteamento Possibilidade de rotear pedidos para os serviços

de backend baseado em alguns critérios

(considerando roteamento estático e dinâmico).

Sim Sim

Transformações/Mapeamento Possibilidade de converter e disponibilizar o

conteúdo do pedido de entrada no formato

reconhecido pelo serviço (e.g. SOAP em REST e

vice-versa), através do mesmo endpoint de

origem.

Não19 Sim

Orquestração Coordenação a baixo nível entre diversas

implementações de serviços (e.g. composição

de workflows que processam pedidos a diversos

serviços).

Sim Sim

Suporte a Protocolos/Mediação Suporte nativo a SOAP e REST e à possibilidade

de mediar entre os vários protocolos.

Não20 Sim

16 A organização dos critérios de avaliação baseou-se no seguinte estudo sobre “API Management Platforms”, realizado pela Syntel: http://www.syntelinc.com/sites/default/files/api_management_platforms_v2.pdf. 17 https://azure.microsoft.com/en-us/services/api-management/ 18 https://feedback.azure.com/forums/248703-api-management/suggestions/5922492-add-monetization-ability-of-api 19 https://feedback.azure.com/forums/248703-api-management/suggestions/6354921-multiple-endpoints 20 https://feedback.azure.com/forums/248703-api-management/suggestions/5782547-soap-support

Service Delivery Broker for API Management 13

Gestão de acessos Suporte a realizar, capturar, registar e gerir

identidades de utilizadores, as suas permissões

de acesso, e os protocolos suportados (e.g.

suporte a OpenID Connect).

Não21 Sim

Analytics Suporte a métricas e relatórios pré-definidos e

personalizados.

Sim Sim

Fornecedores de identidade

personalizados

Possibilidade de configuração de fornecedores

de identidade corporativos e/ou sociais para

todos componentes da solução, incluindo

portais de desenvolvimento, exploração, etc.

Não22 Sim

Personalização do portal para

Developers

Possibilidade de personalização dos elementos

de HTML e estilos de CSS do portal.

Sim23 Sim

Processos ITSM Suporte a Request Fulfillment, Incident

Management e Service Desk.

Não24 Sim

Qualidade de Serviço

Critério Descrição MS API Mng PT SDB

Segurança Suporte nativo a realizar a segurança das APIs

sem necessidade de desenvolvimento de código

para suportar standards de segurança abertos

como OpenID Connect, OAuth 2.0, tokens, e

segurança baseada em políticas.

Não25 Sim

Escalabilidade Escalabilidade horizontal, crescimento e

adequação de um número crescente dos

utilizadores e do volume de transações.

Sim Sim

Desempenho/Latência Latência introduzida pelos proxies, de acordo

com as métricas de desempenho reconhecidas.

Sim Sim

Disponibilidade Resiliência a falhas, sem perda de estado ou

necessidade de interrupção do serviço (e.g.

hot/cold failover).

Sim Sim

21 https://feedback.azure.com/forums/248703-api-management/suggestions/7938420-openid-connect 22 https://feedback.azure.com/forums/248703-api-management/suggestions/5947766-custom-identity-provider-for-the-developer-portal 23 Não disponibiliza APIs ou SDK (Software Developer’s Kit) para a personalização do portal para developers. A configuração do layout e estilos é realizada nos ecrans de administração do portal para o publisher. V. https://feedback.azure.com/forums/248703-api-management/suggestions/5949691-custom-css-support 24 https://feedback.azure.com/forums/255259-azure-pack/suggestions/6041153-support-for-itsm-integration-like-service-manager 25 https://feedback.azure.com/forums/248703-api-management/suggestions/7938420-openid-connect

Service Delivery Broker for API Management 14

Globalização/Suporte a Línguas Suporte a múltiplas línguas e globalização nos

ecrans de administração e no portal para

developers.

Sim26 Sim27

Atualização de versões Frequência e facilidade de atualização, nível de

automação para os processos de atualização.

Sim Sim

Modelos de entrega flexíveis Possibilidade de instalação e exploração da

solução tanto em modelo Cloud como on-

premises do cliente.

Não28 Sim

Notificações flexíveis Controle fino sobre quem recebe as notificações

e personalização do conteúdo das mensagens.

Não29 Sim

Fornecedor

Critério Descrição MS API Mng PT SDB

Mercado e posicionamento Implementações em produção, dimensão, perfil

dos clientes e extensão geográfica.

Sim Sim

Estabilidade financeira Financiamento, faturação, receitas. Sim Sim

Roadmap do produto Roadmap de produto bem definido para os

próximos n anos.

Sim30 Sim31

Suporte e serviço ao cliente Possibilidade de prestar suporte 24x7. Sim32 Sim

Pessoas e Equipas

Critério Descrição MS API Mng PT SDB

Formação Formação adequada, de acordo com as

competências disponíveis na organização.

Sim Sim

Talento Disponibilidade de competência adequada no

mercado.

Sim Sim

Suporte e operações A plataforma e data center são suportados por

equipas especializadas.

Sim Sim

26 https://feedback.azure.com/forums/248703-api-management/suggestions/6143365-locale-translation-of-the-developer-portal 27 O SDB Marketplace suporta Português e Inglês. O SDB Backoffice (portal de administração) apenas suporta Inglês. 28 https://feedback.azure.com/forums/248703-api-management/suggestions/6638917-deploy-api-management-on-site 29 https://feedback.azure.com/forums/248703-api-management/suggestions/10630665-should-be-able-to-customize-all-email-templates e https://feedback.azure.com/forums/248703-api-management/suggestions/6531783-email-notifications-per-api-or-product 30 http://download.microsoft.com/download/4/D/0/4D0FBF6C-8BE9-4032-A9A4-8C5621225D49/Roadmap%201.0.pdf 31 Por forma a ajustar-se mais rapidamente ao feedback dos utilizadores, o roadmap de produto SDB é definido trimestralmente. 32 O serviço de suporte 24x7 tem custos adicionais: https://azure.microsoft.com/en-gb/support/plans/

Service Delivery Broker for API Management 15

8. Histórico de Versões

Versão Data Registo de alterações

0.3 2016-02-06 Correções do texto e da formatação.

0.2 2016-02-05 Reorganização do conteúdo e novo template.

0.1 2016-02-03 Versão inicial.